Arnd's wxversion support.

IPython/Shell.py

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

IPython/UserConfig/ipythonrc

@@ -1,587 +1,597 b''
 # -*- Mode: Shell-Script -*-  Not really, but shows comments correctly
-# $Id: ipythonrc 990 2006-01-04 06:59:02Z fperez $
+# $Id: ipythonrc 998 2006-01-09 06:57:40Z fperez $
 
 #***************************************************************************
 #
 # Configuration file for IPython -- ipythonrc format
 #
 # The format of this file is simply one of 'key value' lines.
 # Lines containing only whitespace at the beginning and then a # are ignored
 # as comments. But comments can NOT be put on lines with data.
 
 # The meaning and use of each key are explained below.
 
 #---------------------------------------------------------------------------
 # Section: included files
 
 # Put one or more *config* files (with the syntax of this file) you want to
 # include. For keys with a unique value the outermost file has precedence. For
 # keys with multiple values, they all get assembled into a list which then
 # gets loaded by IPython.
 
 # In this file, all lists of things should simply be space-separated.
 
 # This allows you to build hierarchies of files which recursively load
 # lower-level services. If this is your main ~/.ipython/ipythonrc file, you
 # should only keep here basic things you always want available. Then you can
 # include it in every other special-purpose config file you create.
 include 
 
 #---------------------------------------------------------------------------
 # Section: startup setup
 
 # These are mostly things which parallel a command line option of the same
 # name.
 
 # Keys in this section should only appear once. If any key from this section
 # is encountered more than once, the last value remains, all earlier ones get
 # discarded.
 
 
 # Automatic calling of callable objects.  If set to 1 or 2, callable objects
 # are automatically called when invoked at the command line, even if you don't
 # type parentheses.  IPython adds the parentheses for you.  For example:
 
 #In [1]: str 45
 #------> str(45)
 #Out[1]: '45'
 
 # IPython reprints your line with '---->' indicating that it added
 # parentheses.  While this option is very convenient for interactive use, it
 # may occasionally cause problems with objects which have side-effects if
 # called unexpectedly.
 
 # The valid values for autocall are:
 
 # autocall 0 -> disabled (you can toggle it at runtime with the %autocall magic)
 
 # autocall 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 [4]: callable
 #------> callable()
 
 # 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'
 
 autocall 1
 
 # Auto-edit syntax errors.  When you use the %edit magic in ipython to edit
 # source code (see the 'editor' variable below), it is possible that you save
 # a file with syntax errors in it.  If this variable is true, IPython will ask
 # you whether to re-open the editor immediately to correct such an error.
 
 autoedit_syntax 1
 
 # Auto-indent. IPython can recognize lines ending in ':' and indent the next
 # line, while also un-indenting automatically after 'raise' or 'return'.  
 
 # This feature uses the readline library, so it will honor your ~/.inputrc
 # configuration (or whatever file your INPUTRC variable points to).  Adding
 # the following lines to your .inputrc file can make indent/unindenting more
 # convenient (M-i indents, M-u unindents):
 
 #  $if Python
 #  "\M-i": "    "
 #  "\M-u": "\d\d\d\d"
 #  $endif
 
 # The feature is potentially a bit dangerous, because it can cause problems
 # with pasting of indented code (the pasted code gets re-indented on each
 # line).  But it's a huge time-saver when working interactively.  The magic
 # function @autoindent allows you to toggle it on/off at runtime.
 
 autoindent 1
 
 # Auto-magic. This gives you access to all the magic functions without having
 # to prepend them with an @ sign. If you define a variable with the same name
 # as a magic function (say who=1), you will need to access the magic function
 # with @ (@who in this example). However, if later you delete your variable
 # (del who), you'll recover the automagic calling form.
 
 # Considering that many magic functions provide a lot of shell-like
 # functionality, automagic gives you something close to a full Python+system
 # shell environment (and you can extend it further if you want).
 
 automagic 1
 
 # Size of the output cache. After this many entries are stored, the cache will
 # get flushed. Depending on the size of your intermediate calculations, you
 # may have memory problems if you make it too big, since keeping things in the
 # cache prevents Python from reclaiming the memory for old results. Experiment
 # with a value that works well for you.
 
 # If you choose cache_size 0 IPython will revert to python's regular >>>
 # unnumbered prompt. You will still have _, __ and ___ for your last three
 # results, but that will be it.  No dynamic _1, _2, etc. will be created. If
 # you are running on a slow machine or with very limited memory, this may
 # help.
 
 cache_size 1000
 
 # Classic mode: Setting 'classic 1' you lose many of IPython niceties,
 # but that's your choice! Classic 1 -> same as IPython -classic.
 # Note that this is _not_ the normal python interpreter, it's simply
 # IPython emulating most of the classic interpreter's behavior.
 classic 0
 
 # colors - Coloring option for prompts and traceback printouts.
 
 # Currently available schemes: NoColor, Linux, LightBG.
 
 # This option allows coloring the prompts and traceback printouts. This
 # requires a terminal which can properly handle color escape sequences. If you
 # are having problems with this, use the NoColor scheme (uses no color escapes
 # at all).
 
 # The Linux option works well in linux console type environments: dark
 # background with light fonts.
 
 # LightBG is similar to Linux but swaps dark/light colors to be more readable
 # in light background terminals.
 
 # keep uncommented only the one you want:
 colors Linux
 #colors LightBG
 #colors NoColor
 
 ########################
 # Note to Windows users
 #
 # Color and readline support is avaialble to Windows users via Gary Bishop's
 # readline library.  You can find Gary's tools at
 # http://sourceforge.net/projects/uncpythontools.
 # Note that his readline module requires in turn the ctypes library, available
 # at http://starship.python.net/crew/theller/ctypes.
 ########################
 
 # color_info: IPython can display information about objects via a set of
 # functions, and optionally can use colors for this, syntax highlighting
 # source code and various other elements. This information is passed through a
 # pager (it defaults to 'less' if $PAGER is not set). 
 
 # If your pager has problems, try to setting it to properly handle escapes
 # (see the less manpage for detail), or disable this option.  The magic
 # function @color_info allows you to toggle this interactively for testing.
 
 color_info 1
 
 # confirm_exit: set to 1 if you want IPython to confirm when you try to exit
 # with an EOF (Control-d in Unix, Control-Z/Enter in Windows). Note that using
 # the magic functions @Exit or @Quit you can force a direct exit, bypassing
 # any confirmation.
 
 confirm_exit 1
 
 # Use deep_reload() as a substitute for reload() by default. deep_reload() is
 # still available as dreload() and appears as a builtin.
 
 deep_reload 0
 
 # Which editor to use with the @edit command. If you leave this at 0, IPython
 # will honor your EDITOR environment variable. Since this editor is invoked on
 # the fly by ipython and is meant for editing small code snippets, you may
 # want to use a small, lightweight editor here.
 
 # For Emacs users, setting up your Emacs server properly as described in the
 # manual is a good idea. An alternative is to use jed, a very light editor
 # with much of the feel of Emacs (though not as powerful for heavy-duty work).
 
 editor 0
 
 # log 1 -> same as ipython -log. This automatically logs to ./ipython.log
 log 0
 
 # Same as ipython -Logfile YourLogfileName. 
 # Don't use with log 1 (use one or the other)
 logfile ''
 
 # banner 0 -> same as ipython -nobanner
 banner 1
 
 # messages 0 -> same as ipython -nomessages
 messages 1
 
 # Automatically call the pdb debugger after every uncaught exception. If you
 # are used to debugging using pdb, this puts you automatically inside of it
 # after any call (either in IPython or in code called by it) which triggers an
 # exception which goes uncaught.
 pdb 0
 
 # Enable the pprint module for printing. pprint tends to give a more readable
 # display (than print) for complex nested data structures.
 pprint 1
 
 # Prompt strings
 
 # Most bash-like escapes can be used to customize IPython's prompts, as well as
 # a few additional ones which are IPython-specific.  All valid prompt escapes
 # are described in detail in the Customization section of the IPython HTML/PDF
 # manual.
 
 # Use \# to represent the current prompt number, and quote them to protect
 # spaces.
 prompt_in1 'In [\#]: '
 
 # \D is replaced by as many dots as there are digits in the
 # current value of \#.
 prompt_in2 '   .\D.: '
 
 prompt_out 'Out[\#]: '
 
 # Select whether to left-pad the output prompts to match the length of the
 # input ones.  This allows you for example to use a simple '>' as an output
 # prompt, and yet have the output line up with the input.  If set to false,
 # the output prompts will be unpadded (flush left).
 prompts_pad_left 1
 
 # quick 1 -> same as ipython -quick
 quick 0
 
 # Use the readline library (1) or not (0). Most users will want this on, but
 # if you experience strange problems with line management (mainly when using
 # IPython inside Emacs buffers) you may try disabling it. Not having it on
 # prevents you from getting command history with the arrow keys, searching and
 # name completion using TAB.
 
 readline 1
 
 # Screen Length: number of lines of your screen. This is used to control
 # printing of very long strings. Strings longer than this number of lines will
 # be paged with the less command instead of directly printed.
 
 # The default value for this is 0, which means IPython will auto-detect your
 # screen size every time it needs to print. If for some reason this isn't
 # working well (it needs curses support), specify it yourself. Otherwise don't
 # change the default.
 
 screen_length 0
 
 # Prompt separators for input and output.
 # Use \n for newline explicitly, without quotes.
 # Use 0 (like at the cmd line) to turn off a given separator.
 
 # The structure of prompt printing is:
 # (SeparateIn)Input....
 # (SeparateOut)Output...
 # (SeparateOut2),   # that is, no newline is printed after Out2
 # By choosing these you can organize your output any way you want.
 
 separate_in \n
 separate_out 0
 separate_out2 0
 
 # 'nosep 1' is a shorthand for '-SeparateIn 0 -SeparateOut 0 -SeparateOut2 0'.
 # Simply removes all input/output separators, overriding the choices above.
 nosep 0
 
 # Wildcard searches - IPython has a system for searching names using
 # shell-like wildcards; type %psearch? for details.  This variables sets
 # whether by default such searches should be case sensitive or not.  You can
 # always override the default at the system command line or the IPython
 # prompt.
 
 wildcards_case_sensitive 1
 
 # xmode - Exception reporting mode. 
 
 # Valid modes: Plain, Context and Verbose.
 
 # Plain: similar to python's normal traceback printing.
 
 # Context: prints 5 lines of context source code around each line in the
 # traceback.
 
 # Verbose: similar to Context, but additionally prints the variables currently
 # visible where the exception happened (shortening their strings if too
 # long). This can potentially be very slow, if you happen to have a huge data
 # structure whose string representation is complex to compute. Your computer
 # may appear to freeze for a while with cpu usage at 100%. If this occurs, you
 # can cancel the traceback with Ctrl-C (maybe hitting it more than once).
 
 #xmode Plain
 xmode Context
 #xmode Verbose
 
 # multi_line_specials: if true, allow magics, aliases and shell escapes (via
 # !cmd) to be used in multi-line input (like for loops).  For example, if you
 # have this active, the following is valid in IPython:
 #
 #In [17]: for i in range(3):
 #   ....:     mkdir $i
 #   ....:     !touch $i/hello
 #   ....:     ls -l $i
 
 multi_line_specials 1
 
+# wxversion: request a specific wxPython version (used for -wthread)
+
+# Set this to the value of wxPython you want to use, but note that this
+# feature requires you to have the wxversion Python module to work.  If you
+# don't have the wxversion module (try 'import wxversion' at the prompt to
+# check) or simply want to leave the system to pick up the default, leave this
+# variable at 0.
+
+wxversion 0
+
 #---------------------------------------------------------------------------
 # Section: Readline configuration (readline is not available for MS-Windows)
 
 # This is done via the following options:
 
 # (i) readline_parse_and_bind: this option can appear as many times as you
 # want, each time defining a string to be executed via a
 # readline.parse_and_bind() command. The syntax for valid commands of this
 # kind can be found by reading the documentation for the GNU readline library,
 # as these commands are of the kind which readline accepts in its
 # configuration file.
 
 # The TAB key can be used to complete names at the command line in one of two
 # ways: 'complete' and 'menu-complete'. The difference is that 'complete' only
 # completes as much as possible while 'menu-complete' cycles through all
 # possible completions. Leave the one you prefer uncommented.
 
 readline_parse_and_bind tab: complete
 #readline_parse_and_bind tab: menu-complete
 
 # This binds Control-l to printing the list of all possible completions when
 # there is more than one (what 'complete' does when hitting TAB twice, or at
 # the first TAB if show-all-if-ambiguous is on)
 readline_parse_and_bind "\C-l": possible-completions
 
 # This forces readline to automatically print the above list when tab
 # completion is set to 'complete'. You can still get this list manually by
 # using the key bound to 'possible-completions' (Control-l by default) or by
 # hitting TAB twice. Turning this on makes the printing happen at the first
 # TAB.
 readline_parse_and_bind set show-all-if-ambiguous on
 
 # If you have TAB set to complete names, you can rebind any key (Control-o by
 # default) to insert a true TAB character.
 readline_parse_and_bind "\C-o": tab-insert
 
 # These commands allow you to indent/unindent easily, with the 4-space
 # convention of the Python coding standards.  Since IPython's internal
 # auto-indent system also uses 4 spaces, you should not change the number of
 # spaces in the code below.
 readline_parse_and_bind "\M-i": "    "
 readline_parse_and_bind "\M-o": "\d\d\d\d"
 readline_parse_and_bind "\M-I": "\d\d\d\d"
 
 # Bindings for incremental searches in the history. These searches use the
 # string typed so far on the command line and search anything in the previous
 # input history containing them.
 readline_parse_and_bind "\C-r": reverse-search-history
 readline_parse_and_bind "\C-s": forward-search-history
 
 # Bindings for completing the current line in the history of previous
 # commands. This allows you to recall any previous command by typing its first
 # few letters and hitting Control-p, bypassing all intermediate commands which
 # may be in the history (much faster than hitting up-arrow 50 times!)
 readline_parse_and_bind "\C-p": history-search-backward
 readline_parse_and_bind "\C-n": history-search-forward
 
 # I also like to have the same functionality on the plain arrow keys. If you'd
 # rather have the arrows use all the history (and not just match what you've
 # typed so far), comment out or delete the next two lines.
 readline_parse_and_bind "\e[A": history-search-backward
 readline_parse_and_bind "\e[B": history-search-forward
 
 # These are typically on by default under *nix, but not win32.
 readline_parse_and_bind "\C-k": kill-line
 readline_parse_and_bind "\C-u": unix-line-discard
 
 # (ii) readline_remove_delims: a string of characters to be removed from the
 # default word-delimiters list used by readline, so that completions may be
 # performed on strings which contain them.
 
 readline_remove_delims -/~
 
 # (iii) readline_merge_completions: whether to merge the result of all
 # possible completions or not.  If true, IPython will complete filenames,
 # python names and aliases and return all possible completions.  If you set it
 # to false, each completer is used at a time, and only if it doesn't return
 # any completions is the next one used.
 
 # The default order is: [python_matches, file_matches, alias_matches]
 
 readline_merge_completions 1
 
 # (iv) readline_omit__names: normally hitting <tab> after a '.' in a name
 # will complete all attributes of an object, including all the special methods
 # whose names start with single or double underscores (like __getitem__ or
 # __class__).
 
 # This variable allows you to control this completion behavior:
 
 # readline_omit__names 1 -> completion will omit showing any names starting
 # with two __, but it will still show names starting with one _.
 
 # readline_omit__names 2 -> completion will omit all names beginning with one
 # _ (which obviously means filtering out the double __ ones).
 
 # Even when this option is set, you can still see those names by explicitly
 # typing a _ after the period and hitting <tab>: 'name._<tab>' will always
 # complete attribute names starting with '_'.
 
 # This option is off by default so that new users see all attributes of any
 # objects they are dealing with.
 
 readline_omit__names 0
 
 #---------------------------------------------------------------------------
 # Section: modules to be loaded with 'import ...'
 
 # List, separated by spaces, the names of the modules you want to import
 
 # Example:
 # import_mod sys os
 # will produce internally the statements
 # import sys
 # import os
 
 # Each import is executed in its own try/except block, so if one module
 # fails to load the others will still be ok.
 
 import_mod 
 
 #---------------------------------------------------------------------------
 # Section: modules to import some functions from: 'from ... import ...'
 
 # List, one per line, the modules for which you want only to import some
 # functions. Give the module name first and then the name of functions to be
 # imported from that module.
 
 # Example:
 
 # import_some IPython.genutils timing timings
 # will produce internally the statement
 # from IPython.genutils import timing, timings
 
 # timing() and timings() are two IPython utilities for timing the execution of
 # your own functions, which you may find useful.  Just commment out the above
 # line if you want to test them.
 
 # If you have more than one modules_some line, each gets its own try/except
 # block (like modules, see above).
 
 import_some 
 
 #---------------------------------------------------------------------------
 # Section: modules to import all from : 'from ... import *'
 
 # List (same syntax as import_mod above) those modules for which you want to
 # import all functions. Remember, this is a potentially dangerous thing to do,
 # since it is very easy to overwrite names of things you need. Use with
 # caution.
 
 # Example:
 # import_all sys os
 # will produce internally the statements
 # from sys import *
 # from os import *
 
 # As before, each will be called in a separate try/except block.
 
 import_all 
 
 #---------------------------------------------------------------------------
 # Section: Python code to execute.
 
 # Put here code to be explicitly executed (keep it simple!)
 # Put one line of python code per line. All whitespace is removed (this is a
 # feature, not a bug), so don't get fancy building loops here.
 # This is just for quick convenient creation of things you want available.
 
 # Example:
 # execute x = 1
 # execute print 'hello world'; y = z = 'a'
 # will produce internally
 # x = 1
 # print 'hello world'; y = z = 'a'
 # and each *line* (not each statement, we don't do python syntax parsing) is
 # executed in its own try/except block.
 
 execute 
 
 # Note for the adventurous: you can use this to define your own names for the
 # magic functions, by playing some namespace tricks:
 
 # execute __IPYTHON__.magic_pf = __IPYTHON__.magic_profile
 
 # defines @pf as a new name for @profile.
 
 #---------------------------------------------------------------------------
 # Section: Pyhton files to load and execute.
 
 # Put here the full names of files you want executed with execfile(file).  If
 # you want complicated initialization, just write whatever you want in a
 # regular python file and load it from here.
 
 # Filenames defined here (which *must* include the extension) are searched for
 # through all of sys.path. Since IPython adds your .ipython directory to
 # sys.path, they can also be placed in your .ipython dir and will be
 # found. Otherwise (if you want to execute things not in .ipyton nor in
 # sys.path) give a full path (you can use ~, it gets expanded)
 
 # Example:
 # execfile file1.py ~/file2.py
 # will generate
 # execfile('file1.py')
 # execfile('_path_to_your_home/file2.py')
 
 # As before, each file gets its own try/except block.
 
 execfile
 
 # If you are feeling adventurous, you can even add functionality to IPython
 # through here. IPython works through a global variable called __ip which
 # exists at the time when these files are read. If you know what you are doing
 # (read the source) you can add functions to __ip in files loaded here. 
 
 # The file example-magic.py contains a simple but correct example. Try it:
 
 # execfile example-magic.py
 
 # Look at the examples in IPython/iplib.py for more details on how these magic
 # functions need to process their arguments.
 
 #---------------------------------------------------------------------------
 # Section: aliases for system shell commands
 
 # Here you can define your own names for system commands. The syntax is
 # similar to that of the builtin @alias function:
 
 # alias alias_name command_string
 
 # The resulting aliases are auto-generated magic functions (hence usable as
 # @alias_name)
 
 # For example:
 
 # alias myls ls -la
 
 # will define 'myls' as an alias for executing the system command 'ls -la'.
 # This allows you to customize IPython's environment to have the same aliases
 # you are accustomed to from your own shell.
 
 # You can also define aliases with parameters using %s specifiers (one per
 # parameter):
 
 # alias parts echo first %s second %s
 
 # will give you in IPython:
 # >>> @parts A B
 # first A second B
 
 # Use one 'alias' statement per alias you wish to define.
 
 # alias 
 
 #************************* end of file <ipythonrc> ************************

IPython/__init__.py

@@ -1,64 +1,64 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.2 or newer.
 
-$Id: __init__.py 775 2005-09-01 20:24:59Z fperez $"""
+$Id: __init__.py 998 2006-01-09 06:57:40Z 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.
 #*****************************************************************************
 
 # Enforce proper version requirements
 import sys
-if sys.version[0:3] < '2.2':
-    raise ImportError, 'Python Version 2.2 or above is required.'
+if sys.version[0:3] < '2.3':
+    raise ImportError, 'Python Version 2.3 or above is required.'
         
 # Define what gets imported with a 'from IPython import *'
 __all__ = ['deep_reload','genutils','ultraTB','DPyGetOpt','Itpl','hooks',
            'ConfigLoader','OutputTrap','Release','Struct','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__:
     __import__(name,glob,loc,[])
 
 # 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/ipmaker.py

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

IPython/usage.py

@@ -1,589 +1,599 b''
 # -*- coding: utf-8 -*-
 #*****************************************************************************
 #       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.
 #*****************************************************************************
 
-# $Id: usage.py 990 2006-01-04 06:59:02Z fperez $
+# $Id: usage.py 998 2006-01-09 06:57:40Z fperez $
 
 from IPython import Release
 __author__  = '%s <%s>' % Release.authors['Fernando']
 __license__ = Release.license
 __version__ = Release.version
 
 __doc__ = """
 IPython -- An enhanced Interactive Python
 =========================================
 
 A Python shell with automatic history (input and output), dynamic object
 introspection, easier configuration, command completion, access to the system
 shell and more.
 
 IPython can also be embedded in running programs. See EMBEDDING below.
 
 
 USAGE
        ipython [options] files
 
        If invoked with no options, it executes all the files listed in
        sequence and drops you into the interpreter while still acknowledging
        any options you may have set in your ipythonrc file. This behavior is
        different from standard Python, which when called as python -i will
        only execute one file and will ignore your configuration setup.
 
        Please note that some of the configuration options are not available at
        the command line, simply because they are not practical here. Look into
        your ipythonrc configuration file for details on those. This file
        typically installed in the $HOME/.ipython directory.
 
        For Windows users, $HOME resolves to C:\\Documents and
        Settings\\YourUserName in most instances, and _ipython is used instead
        of .ipython, since some Win32 programs have problems with dotted names
        in directories.
 
        In the rest of this text, we will refer to this directory as
        IPYTHONDIR.
 
 
 SPECIAL THREADING OPTIONS
        The following special options are ONLY valid at the  beginning  of  the
        command line, and not later.  This is because they control the initial-
        ization of ipython itself, before the normal option-handling  mechanism
        is active.
 
        -gthread, -qthread, -wthread, -pylab
 
               Only ONE of these can be given, and it can only be given as the
               first option passed to IPython (it will have no effect in any
               other position).  They provide threading support for the GTK, QT
               and WXWidgets toolkits, and for the matplotlib library.
 
               With any of the first three options, IPython starts running a
               separate thread for the graphical toolkit's operation, so that
               you can open and control graphical elements from within an
               IPython command line, without blocking.  All three provide
               essentially the same functionality, respectively for GTK, QT and
               WXWidgets (via their Python interfaces).
 
+              Note that with -wthread, you can additionally use the -wxversion
+              option to request a specific version of wx to be used.  This
+              requires that you have the 'wxversion' Python module installed,
+              which is part of recent wxPython distributions.
+
               If -pylab is given, IPython loads special support for the mat-
               plotlib library (http://matplotlib.sourceforge.net), allowing
               interactive usage of any of its backends as defined in the
               user's .matplotlibrc file.  It automatically activates GTK, QT
               or WX threading for IPyhton if the choice of matplotlib backend
               requires it.  It also modifies the %run command to correctly
               execute (without blocking) any matplotlib-based script which
               calls show() at the end.
 
        -tk    The -g/q/wthread options, and -pylab (if matplotlib is
               configured to use GTK, QT or WX), will normally block Tk
               graphical interfaces.  This means that when GTK, QT or WX
               threading is active, any attempt to open a Tk GUI will result in
               a dead window, and possibly cause the Python interpreter to
               crash.  An extra option, -tk, is available to address this
               issue.  It can ONLY be given as a SECOND option after any of the
               above (-gthread, -qthread, -wthread or -pylab).
 
               If -tk is given, IPython will try to coordinate Tk threading
               with GTK, QT or WX.  This is however potentially unreliable, and
               you will have to test on your platform and Python configuration
               to determine whether it works for you.  Debian users have
               reported success, apparently due to the fact that Debian builds
               all of Tcl, Tk, Tkinter and Python with pthreads support.  Under
               other Linux environments (such as Fedora Core 2/3), this option
               has caused random crashes and lockups of the Python interpreter.
               Under other operating systems (Mac OSX and Windows), you'll need
               to try it to find out, since currently no user reports are
               available.
 
               There is unfortunately no way for IPython to determine  at  run-
               time  whether -tk will work reliably or not, so you will need to
               do some experiments before relying on it for regular work.
 
 A WARNING ABOUT SIGNALS AND THREADS
 
        When any of the thread systems (GTK, QT or WX) are active, either
        directly or via -pylab with a threaded backend, it is impossible to
        interrupt long-running Python code via Ctrl-C.  IPython can not pass
        the KeyboardInterrupt exception (or the underlying SIGINT) across
        threads, so any long-running process started from IPython will run to
        completion, or will have to be killed via an external (OS-based)
        mechanism.
 
        To the best of my knowledge, this limitation is imposed by the Python
        interpreter itself, and it comes from the difficulty of writing
        portable signal/threaded code.  If any user is an expert on this topic
        and can suggest a better solution, I would love to hear about it.  In
        the IPython sources, look at the Shell.py module, and in particular at
        the runcode() method.
 
 REGULAR OPTIONS
        After the above threading options have been given, regular options  can
        follow  in any order.  All options can be abbreviated to their shortest
        non-ambiguous form and are case-sensitive.  One or two  dashes  can  be
        used.   Some options have an alternate short form, indicated after a |.
 
        Most options can also be set from your  ipythonrc  configuration  file.
        See the provided examples for assistance.  Options given on the comman-
        dline override the values set in the ipythonrc file.
 
        All options with a [no] prepended can be specified in negated form
        (using -nooption instead of -option) to turn the feature off.
 
        -h, --help
               Show summary of options.
 
        -pylab This can only be given as the first option passed to IPython (it
               will have no effect in any other position). It adds special sup-
               port   for  the  matplotlib  library  (http://matplotlib.source-
               forge.net), allowing interactive usage of any of its backends as
               defined  in  the  user’s  .matplotlibrc  file.  It automatically
               activates GTK or WX threading for IPyhton if the choice of  mat-
               plotlib  backend requires it.  It also modifies the @run command
               to correctly execute  (without  blocking)  any  matplotlib-based
               script which calls show() at the end.
 
        -autocall <val>
               Make IPython automatically call any callable object even if you
               didn't type explicit parentheses. For example, 'str 43' becomes
               'str(43)' automatically.  The value can be '0' to disable the
               feature, '1' for 'smart' autocall, where it is not applied if
               there are no more arguments on the line, and '2' for 'full'
               autocall, where all callable objects are automatically called
               (even if no arguments are present).  The default is '1'.
 
        -[no]autoindent
               Turn automatic indentation on/off.
 
        -[no]automagic
               Make magic commands automatic (without needing their first char-
               acter to be %).  Type %magic at  the  IPython  prompt  for  more
               information.
 
        -[no]autoedit_syntax
               When a syntax error occurs after editing a file, automatically
               open the file to the trouble causing line for convenient fixing.
 
        -[no]banner
               Print the intial information banner (default on).
 
        -c <command>
               Execute  the  given  command  string, and set sys.argv to [’c’].
               This is similar to the -c option in  the  normal  Python  inter-
               preter.
 
        -cache_size|cs <n>
               Size  of  the output cache (maximum number of entries to hold in
               memory).  The default is 1000, you can change it permanently  in
               your  config  file.   Setting  it  to  0 completely disables the
               caching system, and the minimum value accepted  is  20  (if  you
               provide  a value less than 20, it is reset to 0 and a warning is
               issued).  This limit is defined because otherwise  you’ll  spend
               more time re-flushing a too small cache than working.
 
        -classic|cl
               Gives IPython a similar feel to the classic Python prompt.
 
        -colors <scheme>
               Color  scheme  for  prompts  and exception reporting.  Currently
               implemented: NoColor, Linux, and LightBG.
 
        -[no]color_info
               IPython can display information about objects via a set of func-
               tions, and optionally can use colors for this, syntax highlight-
               ing source code and various other  elements.   However,  because
               this  information  is  passed  through a pager (like ’less’) and
               many pagers get confused with color codes, this option is off by
               default.   You  can  test  it and turn it on permanently in your
               ipythonrc file if it works for you.  As a reference, the  ’less’
               pager  supplied  with  Mandrake 8.2 works ok, but that in RedHat
               7.2 doesn’t.
 
               Test it and turn it on permanently if it works with your system.
               The  magic function @color_info allows you to toggle this inter-
               actively for testing.
 
        -[no]confirm_exit
               Set to confirm when you try to exit IPython with  an  EOF  (Con-
               trol-D in Unix, Control-Z/Enter in Windows). Note that using the
               magic functions @Exit or @Quit you  can  force  a  direct  exit,
               bypassing any confirmation.
 
        -[no]debug
               Show  information  about the loading process. Very useful to pin
               down problems with your configuration files or  to  get  details
               about session restores.
 
        -[no]deep_reload
               IPython  can use the deep_reload module which reloads changes in
               modules recursively (it replaces the reload() function,  so  you
               don’t need to change anything to use it). deep_reload() forces a
               full reload of modules whose code may have  changed,  which  the
               default reload() function does not.
 
               When  deep_reload  is off, IPython will use the normal reload(),
               but deep_reload will still be available as dreload(). This  fea-
               ture  is  off  by default [which means that you have both normal
               reload() and dreload()].
 
        -editor <name>
               Which editor to use with the @edit command. By default,  IPython
               will  honor  your EDITOR environment variable (if not set, vi is
               the Unix default and notepad the Windows one). Since this editor
               is  invoked on the fly by IPython and is meant for editing small
               code snippets, you may want to use a small,  lightweight  editor
               here (in case your default EDITOR is something like Emacs).
 
        -ipythondir <name>
               The  name  of  your  IPython configuration directory IPYTHONDIR.
               This can also be  specified  through  the  environment  variable
               IPYTHONDIR.
 
        -log|l Generate  a log file of all input. The file is named
               ipython_log.py in your current directory (which prevents logs
               from multiple IPython sessions from trampling each other). You
               can use this to later restore a session by loading your logfile
               as a file to be executed with option -logplay (see below).
 
        -logfile|lf
               Specify the name of your logfile.
 
        -logplay|lp
               Replay  a previous log. For restoring a session as close as pos-
               sible to the state you left it in, use this option  (don’t  just
               run the logfile). With -logplay, IPython will try to reconstruct
               the previous working environment in full, not just  execute  the
               commands in the logfile.
               When  a  session is restored, logging is automatically turned on
               again with the name of the logfile it was invoked  with  (it  is
               read  from the log header). So once you’ve turned logging on for
               a session, you can quit IPython and reload it as many  times  as
               you  want  and  it  will continue to log its history and restore
               from the beginning every time.
 
               Caveats: there are limitations in this option. The history vari-
               ables  _i*,_* and _dh don’t get restored properly. In the future
               we will try to implement full  session  saving  by  writing  and
               retrieving  a failed because of inherent limitations of Python’s
               Pickle module, so this may have to wait.
 
        -[no]messages
               Print messages which IPython collects about its startup  process
               (default on).
 
        -[no]pdb
               Automatically  call the pdb debugger after every uncaught excep-
               tion. If you are used to debugging  using  pdb,  this  puts  you
               automatically  inside of it after any call (either in IPython or
               in code called by it) which triggers  an  exception  which  goes
               uncaught.
 
        -[no]pprint
               IPython  can  optionally  use the pprint (pretty printer) module
               for displaying results. pprint tends to give a nicer display  of
               nested  data structures. If you like it, you can turn it on per-
               manently in your config file (default off).
 
        -profile|p <name>
               Assume that your config file is ipythonrc-<name> (looks in  cur-
               rent dir first, then in IPYTHONDIR). This is a quick way to keep
               and load multiple config files for different  tasks,  especially
               if  you  use  the include option of config files. You can keep a
               basic IPYTHONDIR/ipythonrc file and then have  other  ’profiles’
               which  include  this  one  and  load extra things for particular
               tasks. For example:
 
               1) $HOME/.ipython/ipythonrc : load basic things you always want.
               2)  $HOME/.ipython/ipythonrc-math  :  load  (1)  and basic math-
               related modules.
               3) $HOME/.ipython/ipythonrc-numeric : load (1) and  Numeric  and
               plotting modules.
 
               Since  it is possible to create an endless loop by having circu-
               lar file inclusions, IPython will stop if it reaches  15  recur-
               sive inclusions.
 
        -prompt_in1|pi1 <string>
               Specify  the string used for input prompts. Note that if you are
               using numbered prompts, the number is represented with a ’\#’ in
               the  string.  Don’t forget to quote strings with spaces embedded
               in them. Default: ’In [\#]:’.
 
               Most bash-like  escapes  can  be  used  to  customize  IPython’s
               prompts, as well as a few additional ones which are IPython-spe-
               cific.  All valid prompt escapes are described in detail in  the
               Customization section of the IPython HTML/PDF manual.
 
        -prompt_in2|pi2 <string>
               Similar  to  the  previous option, but used for the continuation
               prompts. The special sequence ’\D’ is similar to ’\#’, but  with
               all  digits  replaced  dots  (so  you can have your continuation
               prompt aligned with your  input  prompt).  Default:  ’    .\D.:’
               (note three spaces at the start for alignment with ’In [\#]’).
 
        -prompt_out|po <string>
               String   used   for  output  prompts,  also  uses  numbers  like
               prompt_in1.  Default: ’Out[\#]:’.
 
        -quick Start in bare bones mode (no config file loaded).
 
        -rcfile <name>
               Name of your  IPython  resource  configuration  file.   normally
               IPython    loads   ipythonrc   (from   current   directory)   or
               IPYTHONDIR/ipythonrc.  If the loading of your config file fails,
               IPython  starts  with  a  bare  bones  configuration (no modules
               loaded at all).
 
        -[no]readline
               Use the readline library, which is needed to support  name  com-
               pletion  and  command history, among other things. It is enabled
               by default, but may cause  problems  for  users  of  X/Emacs  in
               Python comint or shell buffers.
 
               Note  that  emacs ’eterm’ buffers (opened with M-x term) support
               IPython’s readline and syntax coloring fine, only  ’emacs’  (M-x
               shell and C-c !)  buffers do not.
 
        -screen_length|sl <n>
               Number  of lines of your screen.  This is used to control print-
               ing of very long strings.  Strings longer than  this  number  of
               lines  will be sent through a pager instead of directly printed.
 
               The default value for this is 0, which means IPython will  auto-
               detect  your  screen  size  every time it needs to print certain
               potentially long strings (this doesn’t change  the  behavior  of
               the  ’print’  keyword,  it’s  only triggered internally). If for
               some reason this isn’t working well (it needs  curses  support),
               specify it yourself. Otherwise don’t change the default.
 
        -separate_in|si <string>
               Separator before input prompts.  Default ’0.
 
        -separate_out|so <string>
               Separator before output prompts.  Default: 0 (nothing).
 
        -separate_out2|so2 <string>
               Separator after output prompts.  Default: 0 (nothing).
 
        -nosep Shorthand for ’-separate_in 0 -separate_out 0 -separate_out2 0’.
               Simply removes all input/output separators.
 
        -upgrade
               Allows you to upgrade your  IPYTHONDIR  configuration  when  you
               install  a  new  version  of  IPython.   Since  new versions may
               include new command lines options or example files, this  copies
               updated ipythonrc-type files.  However, it backs up (with a .old
               extension) all files which it overwrites so that you  can  merge
               back any custimizations you might have in your personal files.
 
        -Version
               Print version information and exit.
 
+       -wxversion <string>
+              Select a specific version of wxPython (used in conjunction with
+              -wthread). Requires the wxversion module, part of recent
+              wxPython distributions.
+
        -xmode <modename>
               Mode  for  exception reporting.  The valid modes are Plain, Con-
               text, and Verbose.
 
               - Plain: similar to python’s normal traceback printing.
 
               - Context: prints 5 lines of context  source  code  around  each
               line in the traceback.
 
               - Verbose: similar to Context, but additionally prints the vari-
               ables currently visible where the exception happened (shortening
               their  strings if too long).  This can potentially be very slow,
               if you happen to have a huge data structure whose string  repre-
               sentation  is  complex  to compute.  Your computer may appear to
               freeze for a while with cpu usage at 100%.  If this occurs,  you
               can cancel the traceback with Ctrl-C (maybe hitting it more than
               once).
 
 
 EMBEDDING
        It is possible to start an IPython instance inside your own Python pro-
        grams.  In the documentation example files there are some illustrations
        on how to do this.
 
        This feature allows you to evalutate  dynamically  the  state  of  your
        code,  operate  with  your  variables, analyze them, etc.  Note however
        that any changes you make to values while in the shell do NOT propagate
        back  to  the running code, so it is safe to modify your values because
        you won’t break your code in bizarre ways by doing so.
 """
 
 cmd_line_usage = __doc__
 
 #---------------------------------------------------------------------------
 interactive_usage = """
 IPython -- An enhanced Interactive Python
 =========================================
 
 IPython offers a combination of convenient shell features, special commands
 and a history mechanism for both input (command history) and output (results
 caching, similar to Mathematica). It is intended to be a fully compatible
 replacement for the standard Python interpreter, while offering vastly
 improved functionality and flexibility.
 
 At your system command line, type 'ipython -help' to see the command line
 options available. This document only describes interactive features.
 
 Warning: IPython relies on the existence of a global variable called __IP which
 controls the shell itself. If you redefine __IP to anything, bizarre behavior
 will quickly occur.
 
 MAIN FEATURES
 
 * Access to the standard Python help. As of Python 2.1, a help system is
   available with access to object docstrings and the Python manuals. Simply
   type 'help' (no quotes) to access it.
 
 * Magic commands: type %magic for information on the magic subsystem.
 
 * System command aliases, via the %alias command or the ipythonrc config file.
 
 * Dynamic object information:
 
   Typing ?word or word? prints detailed information about an object.  If
   certain strings in the object are too long (docstrings, code, etc.) they get
   snipped in the center for brevity.
 
   Typing ??word or word?? gives access to the full information without
   snipping long strings. Long strings are sent to the screen through the less
   pager if longer than the screen, printed otherwise.
 
   The ?/?? system gives access to the full source code for any object (if
   available), shows function prototypes and other useful information.
 
   If you just want to see an object's docstring, type '%pdoc object' (without
   quotes, and without % if you have automagic on).
 
   Both %pdoc and ?/?? give you access to documentation even on things which are
   not explicitely defined. Try for example typing {}.get? or after import os,
   type os.path.abspath??. The magic functions %pdef, %source and %file operate
   similarly.
 
 * Completion in the local namespace, by typing TAB at the prompt.
 
   At any time, hitting tab will complete any available python commands or
   variable names, and show you a list of the possible completions if there's
   no unambiguous one. It will also complete filenames in the current directory.
 
   This feature requires the readline and rlcomplete modules, so it won't work
   if your Python lacks readline support (such as under Windows).
 
 * Search previous command history in two ways (also requires readline):
 
   - Start typing, and then use Ctrl-p (previous,up) and Ctrl-n (next,down) to
   search through only the history items that match what you've typed so
   far. If you use Ctrl-p/Ctrl-n at a blank prompt, they just behave like
   normal arrow keys.
 
   - Hit Ctrl-r: opens a search prompt. Begin typing and the system searches
   your history for lines that match what you've typed so far, completing as
   much as it can.
 
 * Persistent command history across sessions (readline required).
 
 * Logging of input with the ability to save and restore a working session.
   
 * System escape with !. Typing !ls will run 'ls' in the current directory.
 
 * The reload command does a 'deep' reload of a module: changes made to the
   module since you imported will actually be available without having to exit.
 
 * Verbose and colored exception traceback printouts. See the magic xmode and
   xcolor functions for details (just type %magic).
 
 * Input caching system:
 
   IPython offers numbered prompts (In/Out) with input and output caching. All
   input is saved and can be retrieved as variables (besides the usual arrow
   key recall).
 
   The following GLOBAL variables always exist (so don't overwrite them!):
   _i: stores previous input.
   _ii: next previous.
   _iii: next-next previous.
   _ih : a list of all input _ih[n] is the input from line n.
 
   Additionally, global variables named _i<n> are dynamically created (<n>
   being the prompt counter), such that _i<n> == _ih[<n>]
 
   For example, what you typed at prompt 14 is available as _i14 and _ih[14].
 
   You can create macros which contain multiple input lines from this history,
   for later re-execution, with the %macro function.
 
   The history function %hist allows you to see any part of your input history
   by printing a range of the _i variables. Note that inputs which contain
   magic functions (%) appear in the history with a prepended comment. This is
   because they aren't really valid Python code, so you can't exec them.
 
 * Output caching system:
 
   For output that is returned from actions, a system similar to the input
   cache exists but using _ instead of _i. Only actions that produce a result
   (NOT assignments, for example) are cached. If you are familiar with
   Mathematica, IPython's _ variables behave exactly like Mathematica's %
   variables.
 
   The following GLOBAL variables always exist (so don't overwrite them!):
   _ (one underscore): previous output.
   __ (two underscores): next previous.
   ___ (three underscores): next-next previous.
 
   Global variables named _<n> are dynamically created (<n> being the prompt
   counter), such that the result of output <n> is always available as _<n>.
 
   Finally, a global dictionary named _oh exists with entries for all lines
   which generated output.
 
 * Directory history:
 
   Your history of visited directories is kept in the global list _dh, and the
   magic %cd command can be used to go to any entry in that list.
 
 * Auto-parentheses and auto-quotes (adapted from Nathan Gray's LazyPython)
 
     1. Auto-parentheses
         Callable objects (i.e. functions, methods, etc) can be invoked like
         this (notice the commas between the arguments):
             >>> callable_ob arg1, arg2, arg3
         and the input will be translated to this:
             --> callable_ob(arg1, arg2, arg3)
         You can force auto-parentheses by using '/' as the first character
         of a line.  For example:
             >>> /globals             # becomes 'globals()'
         Note that the '/' MUST be the first character on the line!  This
         won't work:
             >>> print /globals    # syntax error
             
         In most cases the automatic algorithm should work, so you should
         rarely need to explicitly invoke /. One notable exception is if you
         are trying to call a function with a list of tuples as arguments (the
         parenthesis will confuse IPython):
             In [1]: zip (1,2,3),(4,5,6)  # won't work
         but this will work:
             In [2]: /zip (1,2,3),(4,5,6)
             ------> zip ((1,2,3),(4,5,6))
             Out[2]= [(1, 4), (2, 5), (3, 6)]        
 
         IPython tells you that it has altered your command line by
         displaying the new command line preceded by -->.  e.g.:
             In [18]: callable list
             -------> callable (list) 
 
     2. Auto-Quoting
         You can force auto-quoting of a function's arguments by using ',' as
         the first character of a line.  For example:
             >>> ,my_function /home/me   # becomes my_function("/home/me")
 
         If you use ';' instead, the whole argument is quoted as a single
         string (while ',' splits on whitespace):
             >>> ,my_function a b c   # becomes my_function("a","b","c")
             >>> ;my_function a b c   # becomes my_function("a b c")
 
         Note that the ',' MUST be the first character on the line!  This
         won't work:
             >>> x = ,my_function /home/me    # syntax error
 """

doc/ipython.1

@@ -1,395 +1,406 b''
 .\"                                      Hey, EMACS: -*- nroff -*-
 .\" First parameter, NAME, should be all caps
 .\" Second parameter, SECTION, should be 1-8, maybe w/ subsection
 .\" other parameters are allowed: see man(7), man(1)
 .TH IPYTHON 1 "November 30, 2004"
 .\" Please adjust this date whenever revising the manpage.
 .\"
 .\" Some roff macros, for reference:
 .\" .nh        disable hyphenation
 .\" .hy        enable hyphenation
 .\" .ad l      left justify
 .\" .ad b      justify to both left and right margins
 .\" .nf        disable filling
 .\" .fi        enable filling
 .\" .br        insert line break
 .\" .sp <n>    insert n+1 empty lines
 .\" for manpage-specific macros, see man(7) and groff_man(7)
 .\" .SH        section heading
 .\" .SS        secondary section heading
 .\"
 .\"
 .\" To preview this page as plain text: nroff -man ipython.1
 .\"
 .SH NAME
 ipython \- An Enhanced Interactive Python
 .SH SYNOPSIS
 .B ipython
 .RI [ options ] " files" ...
 .SH DESCRIPTION
 An interactive Python shell with automatic history (input and output),
 dynamic object introspection, easier configuration, command
 completion, access to the system shell, integration with numerical and
 scientific computing tools, and more.
 .SH SPECIAL THREADING OPTIONS
 The following special options are ONLY valid at the beginning of the command
 line, and not later.  This is because they control the initialization of
 ipython itself, before the normal option-handling mechanism is active.
 .TP
 .B \-gthread, \-qthread, \-wthread, \-pylab
 Only ONE of these can be given, and it can only be given as the first option
 passed to IPython (it will have no effect in any other position).  They
 provide threading support for the GTK, QT and WXWidgets toolkits, and for the
 matplotlib library.
 .br
 .sp 1
 With any of the first three options, IPython starts running a separate thread
 for the graphical toolkit's operation, so that you can open and control
 graphical elements from within an IPython command line, without blocking.  All
 three provide essentially the same functionality, respectively for GTK, QT and
 WXWidgets (via their Python interfaces).
 .br
 .sp 1
+Note that with \-wthread, you can additionally use the \-wxversion option to
+request a specific version of wx to be used.  This requires that you have the
+'wxversion' Python module installed, which is part of recent wxPython
+distributions.
+.br
+.sp 1
 If \-pylab is given, IPython loads special support for the matplotlib library
 (http://matplotlib.sourceforge.net), allowing interactive usage of any of its
 backends as defined in the user's .matplotlibrc file.  It automatically
 activates GTK, QT or WX threading for IPyhton if the choice of matplotlib
 backend requires it.  It also modifies the %run command to correctly execute
 (without blocking) any matplotlib-based script which calls show() at the end.
 .TP
 .B \-tk
 The \-g/q/wthread options, and \-pylab (if matplotlib is configured to use
 GTK, QT or WX), will normally block Tk graphical interfaces.  This means that
 when GTK, QT or WX threading is active, any attempt to open a Tk GUI will
 result in a dead window, and possibly cause the Python interpreter to crash.
 An extra option, \-tk, is available to address this issue.  It can ONLY be
 given as a SECOND option after any of the above (\-gthread, \-qthread,
 \-wthread or \-pylab).
 .br
 .sp 1
 If \-tk is given, IPython will try to coordinate Tk threading with GTK, QT or
 WX.  This is however potentially unreliable, and you will have to test on your
 platform and Python configuration to determine whether it works for you.
 Debian users have reported success, apparently due to the fact that Debian
 builds all of Tcl, Tk, Tkinter and Python with pthreads support.  Under other
 Linux environments (such as Fedora Core 2), this option has caused random
 crashes and lockups of the Python interpreter.  Under other operating systems
 (Mac OSX and Windows), you'll need to try it to find out, since currently no
 user reports are available.
 .br
 .sp 1
 There is unfortunately no way for IPython to determine at runtime whether \-tk
 will work reliably or not, so you will need to do some experiments before
 relying on it for regular work.
 .
 .SS A WARNING ABOUT SIGNALS AND THREADS
 When any of the thread systems (GTK, QT or WX) are active, either directly or
 via \-pylab with a threaded backend, it is impossible to interrupt
 long-running Python code via Ctrl\-C.  IPython can not pass the
 KeyboardInterrupt exception (or the underlying SIGINT) across threads, so any
 long-running process started from IPython will run to completion, or will have
 to be killed via an external (OS-based) mechanism.
 .br
 .sp 1
 To the best of my knowledge, this limitation is imposed by the Python
 interpreter itself, and it comes from the difficulty of writing portable
 signal/threaded code.  If any user is an expert on this topic and can suggest
 a better solution, I would love to hear about it.  In the IPython sources,
 look at the Shell.py module, and in particular at the runcode() method.
 .
 .SH REGULAR OPTIONS
 After the above threading options have been given, regular options can follow
 in any order.  All options can be abbreviated to their shortest non-ambiguous
 form and are case-sensitive.  One or two dashes can be used.  Some options
 have an alternate short form, indicated after a |.
 .br
 .sp 1
 Most options can also be set from your ipythonrc configuration file.
 See the provided examples for assistance.  Options given on the
 commandline override the values set in the ipythonrc file.
 .br
 .sp 1
 All options with a [no] prepended can be specified in negated form
 (\-nooption instead of \-option) to turn the feature off.
 .TP
 .B \-h, \-\-help
 Show summary of options.
 .TP
 .B \-autocall <val>
 Make IPython automatically call any callable object even if you didn't type
 explicit parentheses. For example, 'str 43' becomes
 'str(43)' automatically.  The value can be '0' to disable the
 feature, '1' for 'smart' autocall, where it is not applied if
 there are no more arguments on the line, and '2' for 'full'
 autocall, where all callable objects are automatically called
 (even if no arguments are present).  The default is '1'.
 .TP
 .B \-[no]autoindent
 Turn automatic indentation on/off.
 .TP
 .B \-[no]automagic
 Make magic commands automatic (without needing their first character
 to be %).  Type %magic at the IPython prompt for more information.
 .TP
 .B \-[no]autoedit_syntax
 When a syntax error occurs after editing a file, automatically open the file
 to the trouble causing line for convenient fixing.
 .TP
 .B \-[no]banner
 Print the intial information banner (default on).
 .TP
 .B \-c <command>
 Execute the given command string, and set sys.argv to ['c'].  This is similar
 to the \-c option in the normal Python interpreter.
 .TP
 .B \-cache_size|cs <n>
 Size of the output cache (maximum number of entries to hold in
 memory).  The default is 1000, you can change it permanently in your
 config file.  Setting it to 0 completely disables the caching system,
 and the minimum value accepted is 20 (if you provide a value less than
 20, it is reset to 0 and a warning is issued).  This limit is defined
 because otherwise you'll spend more time re-flushing a too small cache
 than working.
 .TP
 .B \-classic|cl
 Gives IPython a similar feel to the classic Python prompt.
 .TP
 .B \-colors <scheme>
 Color scheme for prompts and exception reporting.  Currently
 implemented: NoColor, Linux, and LightBG.
 .TP
 .B \-[no]color_info
 IPython can display information about objects via a set of functions,
 and optionally can use colors for this, syntax highlighting source
 code and various other elements.  However, because this information is
 passed through a pager (like 'less') and many pagers get confused with
 color codes, this option is off by default.  You can test it and turn
 it on permanently in your ipythonrc file if it works for you.  As a
 reference, the 'less' pager supplied with Mandrake 8.2 works ok, but
 that in RedHat 7.2 doesn't.
 .br
 .sp 1
 Test it and turn it on permanently if it works with your system.  The
 magic function @color_info allows you to toggle this interactively for
 testing.
 .TP
 .B \-[no]confirm_exit
 Set to confirm when you try to exit IPython with an EOF (Control-D in
 Unix, Control-Z/Enter in Windows). Note that using the magic functions
 @Exit or @Quit you can force a direct exit, bypassing any
 confirmation.
 .TP
 .B \-[no]debug
 Show information about the loading process. Very useful to pin down
 problems with your configuration files or to get details about session
 restores.
 .TP
 .B \-[no]deep_reload
 IPython can use the deep_reload module which reloads changes in
 modules recursively (it replaces the reload() function, so you don't
 need to change anything to use it). deep_reload() forces a full reload
 of modules whose code may have changed, which the default reload()
 function does not.
 .br
 .sp 1
 When deep_reload is off, IPython will use the normal reload(), but
 deep_reload will still be available as dreload(). This feature is off
 by default [which means that you have both normal reload() and
 dreload()].
 .TP
 .B \-editor <name>
 Which editor to use with the @edit command. By default, IPython will
 honor your EDITOR environment variable (if not set, vi is the Unix
 default and notepad the Windows one). Since this editor is invoked on
 the fly by IPython and is meant for editing small code snippets, you
 may want to use a small, lightweight editor here (in case your default
 EDITOR is something like Emacs).
 .TP
 .B \-ipythondir <name>
 The name of your IPython configuration directory IPYTHONDIR.  This can
 also be specified through the environment variable IPYTHONDIR.
 .TP
 .B \-log|l
 Generate a log file of all input. The file is named ipython_log.py in your
 current directory (which prevents logs from multiple IPython sessions from
 trampling each other). You can use this to later restore a session by loading
 your logfile as a file to be executed with option -logplay (see below).
 .TP
 .B \-logfile|lf
 Specify the name of your logfile.
 .TP
 .B \-logplay|lp
 Replay a previous log. For restoring a session as close as possible to
 the state you left it in, use this option (don't just run the
 logfile). With \-logplay, IPython will try to reconstruct the previous
 working environment in full, not just execute the commands in the
 logfile.
 .br
 .sh 1
 When a session is restored, logging is automatically turned on again
 with the name of the logfile it was invoked with (it is read from the
 log header). So once you've turned logging on for a session, you can
 quit IPython and reload it as many times as you want and it will
 continue to log its history and restore from the beginning every time.
 .br
 .sp 1
 Caveats: there are limitations in this option. The history variables
 _i*,_* and _dh don't get restored properly. In the future we will try
 to implement full session saving by writing and retrieving a
 'snapshot' of the memory state of IPython. But our first attempts
 failed because of inherent limitations of Python's Pickle module, so
 this may have to wait.
 .TP
 .B \-[no]messages
 Print messages which IPython collects about its startup process
 (default on).
 .TP
 .B \-[no]pdb
 Automatically call the pdb debugger after every uncaught exception. If
 you are used to debugging using pdb, this puts you automatically
 inside of it after any call (either in IPython or in code called by
 it) which triggers an exception which goes uncaught.
 .TP
 .B \-[no]pprint
 IPython can optionally use the pprint (pretty printer) module for
 displaying results. pprint tends to give a nicer display of nested
 data structures. If you like it, you can turn it on permanently in
 your config file (default off).
 .TP
 .B \-profile|p <name>
 Assume that your config file is ipythonrc-<name> (looks in current dir
 first, then in IPYTHONDIR). This is a quick way to keep and load
 multiple config files for different tasks, especially if you use the
 include option of config files. You can keep a basic
 IPYTHONDIR/ipythonrc file and then have other 'profiles' which include
 this one and load extra things for particular tasks. For example:
 .br
 .sp 1
 1) $HOME/.ipython/ipythonrc : load basic things you always want.
 .br
 2) $HOME/.ipython/ipythonrc-math : load (1) and basic math-related
 modules.
 .br
 3) $HOME/.ipython/ipythonrc-numeric : load (1) and Numeric and
 plotting modules.
 .br
 .sp 1
 Since it is possible to create an endless loop by having circular file
 inclusions, IPython will stop if it reaches 15 recursive inclusions.
 .TP
 .B \-prompt_in1|pi1 <string>
 Specify the string used for input prompts. Note that if you are using
 numbered prompts, the number is represented with a '\\#' in the
 string. Don't forget to quote strings with spaces embedded in
 them. Default: 'In [\\#]:'.
 .br
 .sp 1
 Most bash-like escapes can be used to customize IPython's prompts, as well as
 a few additional ones which are IPython-specific.  All valid prompt escapes
 are described in detail in the Customization section of the IPython HTML/PDF
 manual.
 .TP
 .B \-prompt_in2|pi2 <string>
 Similar to the previous option, but used for the continuation prompts. The
 special sequence '\\D' is similar to '\\#', but with all digits replaced dots
 (so you can have your continuation prompt aligned with your input
 prompt). Default: '   .\\D.:' (note three spaces at the start for alignment
 with 'In [\\#]').
 .TP
 .B \-prompt_out|po <string>
 String used for output prompts, also uses numbers like prompt_in1.
 Default: 'Out[\\#]:'.
 .TP
 .B \-quick
 Start in bare bones mode (no config file loaded).
 .TP
 .B \-rcfile <name>
 Name of your IPython resource configuration file.  normally IPython
 loads ipythonrc (from current directory) or IPYTHONDIR/ipythonrc.  If
 the loading of your config file fails, IPython starts with a bare
 bones configuration (no modules loaded at all).
 .TP
 .B \-[no]readline
 Use the readline library, which is needed to support name completion
 and command history, among other things. It is enabled by default, but
 may cause problems for users of X/Emacs in Python comint or shell
 buffers.
 .br
 .sp 1
 Note that emacs 'eterm' buffers (opened with M-x term) support
 IPython's readline and syntax coloring fine, only 'emacs' (M-x shell
 and C-c !)  buffers do not.
 .TP
 .B \-screen_length|sl <n>
 Number of lines of your screen.  This is used to control printing of
 very long strings.  Strings longer than this number of lines will be
 sent through a pager instead of directly printed.
 .br
 .sp 1
 The default value for this is 0, which means IPython will auto-detect
 your screen size every time it needs to print certain potentially long
 strings (this doesn't change the behavior of the 'print' keyword, it's
 only triggered internally). If for some reason this isn't working well
 (it needs curses support), specify it yourself. Otherwise don't change
 the default.
 .TP
 .B \-separate_in|si <string>
 Separator before input prompts.  Default '\n'.
 .TP
 .B \-separate_out|so <string>
 Separator before output prompts.  Default: 0 (nothing).
 .TP
 .B \-separate_out2|so2 <string>
 Separator after output prompts.  Default: 0 (nothing).
 .TP
 .B \-nosep
 Shorthand for '\-separate_in 0 \-separate_out 0 \-separate_out2 0'.
 Simply removes all input/output separators.
 .TP
 .B \-upgrade
 Allows you to upgrade your IPYTHONDIR configuration when you install a
 new version of IPython.  Since new versions may include new command
 lines options or example files, this copies updated ipythonrc-type
 files.  However, it backs up (with a .old extension) all files which
 it overwrites so that you can merge back any custimizations you might
 have in your personal files.
 .TP
 .B \-Version
 Print version information and exit.
 .TP
+.B -wxversion <string>
+Select a specific version of wxPython (used in conjunction with
+\-wthread). Requires the wxversion module, part of recent wxPython
+distributions.
+.TP
 .B \-xmode <modename>
 Mode for exception reporting.  The valid modes are Plain, Context, and
 Verbose.
 .br
 .sp 1
 \- Plain: similar to python's normal traceback printing.
 .br
 .sp 1
 \- Context: prints 5 lines of context source code around each line in the
 traceback.
 .br
 .sp 1
 \- Verbose: similar to Context, but additionally prints the variables
 currently visible where the exception happened (shortening their strings if
 too long).  This can potentially be very slow, if you happen to have a huge
 data structure whose string representation is complex to compute.  Your
 computer may appear to freeze for a while with cpu usage at 100%.  If this
 occurs, you can cancel the traceback with Ctrl-C (maybe hitting it more than
 once).
 .
 .SH EMBEDDING
 It is possible to start an IPython instance inside your own Python
 programs.  In the documentation example files there are some
 illustrations on how to do this.
 .br
 .sp 1
 This feature allows you to evalutate dynamically the state of your
 code, operate with your variables, analyze them, etc.  Note however
 that any changes you make to values while in the shell do NOT
 propagate back to the running code, so it is safe to modify your
 values because you won't break your code in bizarre ways by doing so.
 .SH AUTHOR
 IPython was written by Fernando Perez <[e-mail]>, based on earlier
 code by Janko Hauser <[e-mail]> and Nathaniel Gray
 <[e-mail]>.  This manual page was written by Jack Moffitt
 <[e-mail]>, for the Debian project (but may be used by others).