Kirill Smelkov patch: try to use 'cProfile' instead of the slower pure python 'profile' module

IPython/Magic.py

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

doc/manual_base.lyx

@@ -1,9545 +1,9549 b''
 #LyX 1.3 created this file. For more info see http://www.lyx.org/
 \lyxformat 221
 \textclass article
 \begin_preamble
 %\usepackage{ae,aecompl}
 \usepackage{color}
 
 % A few colors to replace the defaults for certain link types
 \definecolor{orange}{cmyk}{0,0.4,0.8,0.2}
 \definecolor{darkorange}{rgb}{.71,0.21,0.01}
 \definecolor{darkred}{rgb}{.52,0.08,0.01}
 \definecolor{darkgreen}{rgb}{.12,.54,.11}
 
 % Use and configure listings package for nicely formatted code
 \usepackage{listings}
 \lstset{
   language=Python,
   basicstyle=\small\ttfamily,
   commentstyle=\ttfamily\color{blue},
   stringstyle=\ttfamily\color{darkorange},
   showstringspaces=false,
   breaklines=true,
   postbreak = \space\dots
 }
 
 \usepackage[%pdftex,  % needed for pdflatex
   breaklinks=true,  % so long urls are correctly broken across lines
   colorlinks=true,
   urlcolor=blue,
   linkcolor=darkred,
   citecolor=darkgreen,
   ]{hyperref}
 
 \usepackage{html}
 
 % This helps prevent overly long lines that stretch beyond the margins
 \sloppy
 
 % Define a \codelist command which either uses listings for latex, or
 % plain verbatim for html (since latex2html doesn't understand the 
 % listings package).
 \usepackage{verbatim}
 \newcommand{\codelist}[1] {
 \latex{\lstinputlisting{#1}}
 \html{\verbatiminput{#1}}
 }
 \end_preamble
 \language english
 \inputencoding latin1
 \fontscheme palatino
 \graphics default
 \paperfontsize 11
 \spacing single 
 \papersize Default
 \paperpackage a4
 \use_geometry 1
 \use_amsmath 0
 \use_natbib 0
 \use_numerical_citations 0
 \paperorientation portrait
 \leftmargin 1in
 \topmargin 1in
 \rightmargin 1in
 \bottommargin 1in
 \secnumdepth 3
 \tocdepth 3
 \paragraph_separation skip
 \defskip medskip
 \quotes_language english
 \quotes_times 2
 \papercolumns 1
 \papersides 2
 \paperpagestyle fancy
 
 \layout Title
 
 IPython
 \newline 
 
 \size larger 
 An enhanced Interactive Python
 \size large 
 
 \newline 
 User Manual, v.
  __version__
 \layout Author
 
 Fernando P�rez
 \begin_inset Foot
 collapsed true
 
 \layout Standard
 
 
 \size scriptsize 
 Department of Applied Mathematics, University of Colorado at Boulder.
  
 \family typewriter 
 <[e-mail]>
 \end_inset 
 
 
 \layout Standard
 
 
 \begin_inset ERT
 status Collapsed
 
 \layout Standard
 
 \backslash 
 latex{
 \end_inset 
 
 
 \begin_inset LatexCommand \tableofcontents{}
 
 \end_inset 
 
 
 \begin_inset ERT
 status Collapsed
 
 \layout Standard
 }
 \end_inset 
 
 
 \layout Standard
 
 
 \begin_inset ERT
 status Open
 
 \layout Standard
 
 \backslash 
 html{
 \backslash 
 bodytext{bgcolor=#ffffff}}
 \end_inset 
 
 
 \layout Section
 \pagebreak_top 
 Overview
 \layout Standard
 
 One of Python's most useful features is its interactive interpreter.
  This system 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 somewhat limited for extended interactive use.
 \layout Standard
 
 IPython is a free software project (released under the BSD license) which
  tries to:
 \layout Enumerate
 
 Provide an interactive shell superior to Python's default.
  IPython has many features for object introspection, system shell access,
  and its own special command system for adding functionality when working
  interactively.
  It tries to be a very efficient environment both for Python code development
  and for exploration of problems using Python objects (in situations like
  data analysis).
 \layout Enumerate
 
 Serve as an embeddable, ready to use interpreter for your own programs.
  IPython can be started with a single call from inside another program,
  providing access to the current namespace.
  This can be very useful both for debugging purposes and for situations
  where a blend of batch-processing and interactive exploration are needed.
 \layout Enumerate
 
 Offer a flexible framework which can be used as the base environment for
  other systems with Python as the underlying language.
  Specifically scientific environments like Mathematica, IDL and Matlab inspired
  its design, but similar ideas can be useful in many fields.
 \layout Enumerate
 
 Allow interactive testing of threaded graphical toolkits.
  IPython has support for interactive, non-blocking control of GTK, Qt and
  WX applications via special threading flags.
  The normal Python shell can only do this for Tkinter applications.
 \layout Subsection
 
 Main features
 \layout Itemize
 
 Dynamic object introspection.
  One can access docstrings, function definition prototypes, source code,
  source files and other details of any object accessible to the interpreter
  with a single keystroke (`
 \family typewriter 
 ?
 \family default 
 ', and using `
 \family typewriter 
 ??
 \family default 
 ' provides additional detail).
 \layout Itemize
 
 Searching through modules and namespaces with `
 \family typewriter 
 *
 \family default 
 ' wildcards, both when using the `
 \family typewriter 
 ?
 \family default 
 ' system and via the 
 \family typewriter 
 %psearch
 \family default 
  command.
 \layout Itemize
 
 Completion in the local namespace, by typing TAB at the prompt.
  This works for keywords, methods, variables and files in the current directory.
  This is supported via the readline library, and full access to configuring
  readline's behavior is provided.
 \layout Itemize
 
 Numbered input/output prompts with command history (persistent across sessions
  and tied to each profile), full searching in this history and caching of
  all input and output.
 \layout Itemize
 
 User-extensible `magic' commands.
  A set of commands prefixed with 
 \family typewriter 
 %
 \family default 
  is available for controlling IPython itself and provides directory control,
  namespace information and many aliases to common system shell commands.
 \layout Itemize
 
 Alias facility for defining your own system aliases.
 \layout Itemize
 
 Complete system shell access.
  Lines starting with ! are passed directly to the system shell, and using
  !! captures shell output into python variables for further use.
 \layout Itemize
 
 Background execution of Python commands in a separate thread.
  IPython has an internal job manager called 
 \family typewriter 
 jobs
 \family default 
 , and a conveninence backgrounding magic function called 
 \family typewriter 
 %bg
 \family default 
 .
 \layout Itemize
 
 The ability to expand python variables when calling the system shell.
  In a shell command, any python variable prefixed with 
 \family typewriter 
 $
 \family default 
  is expanded.
  A double 
 \family typewriter 
 $$
 \family default 
  allows passing a literal 
 \family typewriter 
 $
 \family default 
  to the shell (for access to shell and environment variables like 
 \family typewriter 
 $PATH
 \family default 
 ).
 \layout Itemize
 
 Filesystem navigation, via a magic 
 \family typewriter 
 %cd
 \family default 
  command, along with a persistent bookmark system (using 
 \family typewriter 
 %bookmark
 \family default 
 ) for fast access to frequently visited directories.
 \layout Itemize
 
 A lightweight persistence framework via the 
 \family typewriter 
 %store
 \family default 
  command, which allows you to save arbitrary Python variables.
  These get restored automatically when your session restarts.
 \layout Itemize
 
 Automatic indentation (optional) of code as you type (through the readline
  library).
 \layout Itemize
 
 Macro system for quickly re-executing multiple lines of previous input with
  a single name.
  Macros can be stored persistently via 
 \family typewriter 
 %store
 \family default 
  and edited via 
 \family typewriter 
 %edit
 \family default 
 .
  
 \layout Itemize
 
 Session logging (you can then later use these logs as code in your programs).
  Logs can optionally timestamp all input, and also store session output
  (marked as comments, so the log remains valid Python source code).
 \layout Itemize
 
 Session restoring: logs can be replayed to restore a previous session to
  the state where you left it.
 \layout Itemize
 
 Verbose and colored exception traceback printouts.
  Easier to parse visually, and in verbose mode they produce a lot of useful
  debugging information (basically a terminal version of the cgitb module).
 \layout Itemize
 
 Auto-parentheses: callable objects can be executed without parentheses:
  
 \family typewriter 
 `sin 3'
 \family default 
  is automatically converted to 
 \family typewriter 
 `sin(3)
 \family default 
 '.
 \layout Itemize
 
 Auto-quoting: using `
 \family typewriter 
 ,
 \family default 
 ' or `
 \family typewriter 
 ;
 \family default 
 ' as the first character forces auto-quoting of the rest of the line: 
 \family typewriter 
 `,my_function a\SpecialChar ~
 b'
 \family default 
  becomes automatically 
 \family typewriter 
 `my_function("a","b")'
 \family default 
 , while 
 \family typewriter 
 `;my_function a\SpecialChar ~
 b'
 \family default 
  becomes 
 \family typewriter 
 `my_function("a b")'
 \family default 
 .
 \layout Itemize
 
 Extensible input syntax.
  You can define filters that pre-process user input to simplify input in
  special situations.
  This allows for example pasting multi-line code fragments which start with
  
 \family typewriter 
 `>>>'
 \family default 
  or 
 \family typewriter 
 `...'
 \family default 
  such as those from other python sessions or the standard Python documentation.
 \layout Itemize
 
 Flexible configuration system.
  It uses a configuration file which allows permanent setting of all command-line
  options, module loading, code and file execution.
  The system allows recursive file inclusion, so you can have a base file
  with defaults and layers which load other customizations for particular
  projects.
 \layout Itemize
 
 Embeddable.
  You can call IPython as a python shell inside your own python programs.
  This can be used both for debugging code or for providing interactive abilities
  to your programs with knowledge about the local namespaces (very useful
  in debugging and data analysis situations).
 \layout Itemize
 
 Easy debugger access.
  You can set IPython to call up an enhanced version of the Python debugger
  (
 \family typewriter 
 pdb
 \family default 
 ) every time there is an uncaught exception.
  This drops you inside the code which triggered the exception with all the
  data live and it is possible to navigate the stack to rapidly isolate the
  source of a bug.
  The 
 \family typewriter 
 %run
 \family default 
  magic command --with the 
 \family typewriter 
 -d
 \family default 
  option-- can run any script under 
 \family typewriter 
 pdb
 \family default 
 's control, automatically setting initial breakpoints for you.
  This version of 
 \family typewriter 
 pdb
 \family default 
  has IPython-specific improvements, including tab-completion and traceback
  coloring support.
 \layout Itemize
 
 Profiler support.
  You can run single statements (similar to 
 \family typewriter 
 profile.run()
 \family default 
 ) or complete programs under the profiler's control.
- While this is possible with the standard 
+ While this is possible with standard 
+\family typewriter 
+cProfile
+\family default 
+ or 
 \family typewriter 
 profile
 \family default 
- module, IPython wraps this functionality with magic commands (see 
+ modules, IPython wraps this functionality with magic commands (see 
 \family typewriter 
 `%prun'
 \family default 
  and 
 \family typewriter 
 `%run -p
 \family default 
 ') convenient for rapid interactive work.
 \layout Subsection
 
 Portability and Python requirements
 \layout Standard
 
 
 \series bold 
 Python requirements: 
 \series default 
 IPython requires with Python version 2.3 or newer.
  If you are still using Python 2.2 and can not upgrade, the last version
  of IPython which worked with Python 2.2 was 0.6.15, so you will have to use
  that.
 \layout Standard
 
 IPython is developed under 
 \series bold 
 Linux
 \series default 
 , but it should work in any reasonable Unix-type system (tested OK under
  Solaris and the *BSD family, for which a port exists thanks to Dryice Liu).
 \layout Standard
 
 
 \series bold 
 Mac OS X
 \series default 
 : it works, apparently without any problems (thanks to Jim Boyle at Lawrence
  Livermore for the information).
  Thanks to Andrea Riciputi, Fink support is available.
 \layout Standard
 
 
 \series bold 
 CygWin
 \series default 
 : it works mostly OK, though some users have reported problems with prompt
  coloring.
  No satisfactory solution to this has been found so far, you may want to
  disable colors permanently in the 
 \family typewriter 
 ipythonrc
 \family default 
  configuration file if you experience problems.
  If you have proper color support under cygwin, please post to the IPython
  mailing list so this issue can be resolved for all users.
 \layout Standard
 
 
 \series bold 
 Windows
 \series default 
 : it works well under Windows XP/2k, and I suspect NT should behave similarly.
  Section\SpecialChar ~
 
 \begin_inset LatexCommand \ref{sub:Under-Windows}
 
 \end_inset 
 
  describes installation details for Windows, including some additional tools
  needed on this platform.
 \layout Standard
 
 Windows 9x support is present, and has been reported to work fine (at least
  on WinME).
 \layout Standard
 
 Note, that I have very little access to and experience with Windows development.
  However, an excellent group of Win32 users (led by Ville Vainio), consistently
  contribute bugfixes and platform-specific enhancements, so they more than
  make up for my deficiencies on that front.
  In fact, Win32 users report using IPython as a system shell (see Sec.\SpecialChar ~
 
 \begin_inset LatexCommand \ref{sec:IPython-as-shell}
 
 \end_inset 
 
  for details), as it offers a level of control and features which the default
  
 \family typewriter 
 cmd.exe
 \family default 
  doesn't provide.
 \layout Subsection
 
 Location
 \layout Standard
 
 IPython is generously hosted at 
 \begin_inset LatexCommand \htmlurl{http://ipython.scipy.org}
 
 \end_inset 
 
  by the Enthought, Inc and the SciPy project.
  This site offers downloads, subversion access, mailing lists and a bug
  tracking system.
  I am very grateful to Enthought (
 \begin_inset LatexCommand \htmlurl{http://www.enthought.com}
 
 \end_inset 
 
 ) and all of the SciPy team for their contribution.
 \layout Section
 
 
 \begin_inset LatexCommand \label{sec:install}
 
 \end_inset 
 
 Installation
 \layout Subsection
 
 Instant instructions
 \layout Standard
 
 If you are of the impatient kind, under Linux/Unix simply untar/unzip the
  download, then install with 
 \family typewriter 
 `python setup.py install'
 \family default 
 .
  Under Windows, double-click on the provided 
 \family typewriter 
 .exe
 \family default 
  binary installer.
 \layout Standard
 
 Then, take a look at Sections 
 \begin_inset LatexCommand \ref{sec:good_config}
 
 \end_inset 
 
  for configuring things optimally and 
 \begin_inset LatexCommand \ref{sec:quick_tips}
 
 \end_inset 
 
  for quick tips on efficient use of IPython.
  You can later refer to the rest of the manual for all the gory details.
 \layout Standard
 
 See the notes in sec.
  
 \begin_inset LatexCommand \ref{sec:upgrade}
 
 \end_inset 
 
  for upgrading IPython versions.
 \layout Subsection
 
 Detailed Unix instructions (Linux, Mac OS X, etc.)
 \layout Standard
 
 For RPM based systems, simply install the supplied package in the usual
  manner.
  If you download the tar archive, the process is:
 \layout Enumerate
 
 Unzip/untar the 
 \family typewriter 
 ipython-XXX.tar.gz
 \family default 
  file wherever you want (
 \family typewriter 
 XXX
 \family default 
  is the version number).
  It will make a directory called 
 \family typewriter 
 ipython-XXX.
  
 \family default 
 Change into that directory where you will find the files 
 \family typewriter 
 README
 \family default 
  and 
 \family typewriter 
 setup.py
 \family default 
 .
 
 \family typewriter 
  O
 \family default 
 nce you've completed the installation, you can safely remove this directory.
  
 \layout Enumerate
 
 If you are installing over a previous installation of version 0.2.0 or earlier,
  first remove your 
 \family typewriter 
 $HOME/.ipython
 \family default 
  directory, since the configuration file format has changed somewhat (the
  '=' were removed from all option specifications).
  Or you can call ipython with the 
 \family typewriter 
 -upgrade
 \family default 
  option and it will do this automatically for you.
 \layout Enumerate
 
 IPython uses distutils, so you can install it by simply typing at the system
  prompt (don't type the 
 \family typewriter 
 $
 \family default 
 )
 \newline 
 
 \family typewriter 
 $ python setup.py install
 \family default 
 
 \newline 
 Note that this assumes you have root access to your machine.
  If you don't have root access or don't want IPython to go in the default
  python directories, you'll need to use the 
 \begin_inset ERT
 status Collapsed
 
 \layout Standard
 
 \backslash 
 verb|--home|
 \end_inset 
 
  option (or 
 \begin_inset ERT
 status Collapsed
 
 \layout Standard
 
 \backslash 
 verb|--prefix|
 \end_inset 
 
 ).
  For example:
 \newline 
 
 \begin_inset ERT
 status Collapsed
 
 \layout Standard
 
 \backslash 
 verb|$ python setup.py install --home $HOME/local|
 \end_inset 
 
 
 \newline 
 will install IPython into 
 \family typewriter 
 $HOME/local 
 \family default 
 and its subdirectories (creating them if necessary).
 \newline 
 You can type
 \newline 
 
 \begin_inset ERT
 status Collapsed
 
 \layout Standard
 
 \backslash 
 verb|$ python setup.py --help|
 \end_inset 
 
  
 \newline 
 for more details.
 \newline 
 Note that if you change the default location for 
 \begin_inset ERT
 status Collapsed
 
 \layout Standard
 
 \backslash 
 verb|--home|
 \end_inset 
 
  at installation, IPython may end up installed at a location which is not
  part of your 
 \family typewriter 
 $PYTHONPATH
 \family default 
  environment variable.
  In this case, you'll need to configure this variable to include the actual
  directory where the 
 \family typewriter 
 IPython/
 \family default 
  directory ended (typically the value you give to 
 \begin_inset ERT
 status Collapsed
 
 \layout Standard
 
 \backslash 
 verb|--home|
 \end_inset 
 
  plus 
 \family typewriter 
 /lib/python
 \family default 
 ).
 \layout Subsubsection
 
 Mac OSX information
 \layout Standard
 
 Under OSX, there is a choice you need to make.
  Apple ships its own build of Python, which lives in the core OSX filesystem
  hierarchy.
  You can also manually install a separate Python, either purely by hand
  (typically in 
 \family typewriter 
 /usr/local
 \family default 
 ) or by using Fink, which puts everything under 
 \family typewriter 
 /sw
 \family default 
 .
  Which route to follow is a matter of personal preference, as I've seen
  users who favor each of the approaches.
  Here I will simply list the known installation issues under OSX, along
  with their solutions.
 \layout Standard
 
 This page: 
 \begin_inset LatexCommand \htmlurl{http://geosci.uchicago.edu/~tobis/pylab.html}
 
 \end_inset 
 
  contains information on this topic, with additional details on how to make
  IPython and matplotlib play nicely under OSX.
 \layout Subsubsection*
 
 GUI problems
 \layout Standard
 
 The following instructions apply to an install of IPython under OSX from
  unpacking the 
 \family typewriter 
 .tar.gz
 \family default 
  distribution and installing it for the default Python interpreter shipped
  by Apple.
  If you are using a fink install, fink will take care of these details for
  you, by installing IPython against fink's Python.
 \layout Standard
 
 IPython offers various forms of support for interacting with graphical applicati
 ons from the command line, from simple Tk apps (which are in principle always
  supported by Python) to interactive control of WX, Qt and GTK apps.
  Under OSX, however, this requires that ipython is installed by calling
  the special 
 \family typewriter 
 pythonw
 \family default 
  script at installation time, which takes care of coordinating things with
  Apple's graphical environment.
 \layout Standard
 
 So when installing under OSX, it is best to use the following command:
 \family typewriter 
 
 \newline 
 
 \family default 
 
 \begin_inset ERT
 status Collapsed
 
 \layout Standard
 
 \backslash 
 verb|  $ sudo pythonw setup.py install --install-scripts=/usr/local/bin|
 \end_inset 
 
 
 \newline 
  or
 \newline 
 
 \begin_inset ERT
 status Collapsed
 
 \layout Standard
 
 \backslash 
 verb|  $ sudo pythonw setup.py install --install-scripts=/usr/bin|
 \end_inset 
 
 
 \newline 
 depending on where you like to keep hand-installed executables.
 \layout Standard
 
 The resulting script will have an appropriate shebang line (the first line
  in the script whic begins with 
 \family typewriter 
 #!...
 \family default 
 ) such that the ipython interpreter can interact with the OS X GUI.
  If the installed version does not work and has a shebang line that points
  to, for example, just 
 \family typewriter 
 /usr/bin/python
 \family default 
 , then you might have a stale, cached version in your 
 \family typewriter 
 build/scripts-<python-version>
 \family default 
  directory.
  Delete that directory and rerun the 
 \family typewriter 
 setup.py
 \family default 
 .
  
 \layout Standard
 
 It is also a good idea to use the special flag 
 \begin_inset ERT
 status Collapsed
 
 \layout Standard
 
 \backslash 
 verb|--install-scripts|
 \end_inset 
 
  as indicated above, to ensure that the ipython scripts end up in a location
  which is part of your 
 \family typewriter 
 $PATH
 \family default 
 .
  Otherwise Apple's Python will put the scripts in an internal directory
  not available by default at the command line (if you use 
 \family typewriter 
 /usr/local/bin
 \family default 
 , you need to make sure this is in your 
 \family typewriter 
 $PATH
 \family default 
 , which may not be true by default).
 \layout Subsubsection*
 
 Readline problems
 \layout Standard
 
 By default, the Python version shipped by Apple does 
 \emph on 
 not
 \emph default 
  include the readline library, so central to IPython's behavior.
  If you install IPython against Apple's Python, you will not have arrow
  keys, tab completion, etc.
  For Mac OSX 10.3 (Panther), you can find a prebuilt readline library here:
 \newline 
 
 \begin_inset LatexCommand \htmlurl{http://pythonmac.org/packages/readline-5.0-py2.3-macosx10.3.zip}
 
 \end_inset 
 
  
 \layout Standard
 
 If you are using OSX 10.4 (Tiger), after installing this package you need
  to either: 
 \layout Enumerate
 
 move 
 \family typewriter 
 readline.so
 \family default 
  from 
 \family typewriter 
 /Library/Python/2.3
 \family default 
  to 
 \family typewriter 
 /Library/Python/2.3/site-packages
 \family default 
 , or
 \layout Enumerate
 
 install 
 \begin_inset LatexCommand \htmlurl{http://pythonmac.org/packages/TigerPython23Compat.pkg.zip}
 
 \end_inset 
 
 
 \layout Standard
 
 Users installing against Fink's Python or a properly hand-built one should
  not have this problem.
 \layout Subsubsection*
 
 DarwinPorts
 \layout Standard
 
 I report here a message from an OSX user, who suggests an alternative means
  of using IPython under this operating system with good results.
  Please let me know of any updates that may be useful for this section.
  His message is reproduced verbatim below:
 \layout Quote
 
 From: Markus Banfi 
 \family typewriter 
 <markus.banfi-AT-mospheira.net>
 \layout Quote
 
 As a MacOS X (10.4.2) user I prefer to install software using DawinPorts instead
  of Fink.
  I had no problems installing ipython with DarwinPorts.
  It's just:
 \layout Quote
 
 
 \family typewriter 
 sudo port install py-ipython
 \layout Quote
 
 It automatically resolved all dependencies (python24, readline, py-readline).
  So far I did not encounter any problems with the DarwinPorts port of ipython.
  
 \layout Subsection
 
 
 \begin_inset LatexCommand \label{sub:Under-Windows}
 
 \end_inset 
 
 Windows instructions
 \layout Standard
 
 Some of IPython's very useful features are:
 \layout Itemize
 
 Integrated readline support (Tab-based file, object and attribute completion,
  input history across sessions, editable command line, etc.)
 \layout Itemize
 
 Coloring of prompts, code and tracebacks.
 \layout Standard
 
 These, by default, are only available under Unix-like operating systems.
  However, thanks to Gary Bishop's work, Windows XP/2k users can also benefit
  from them.
  His readline library originally implemented both GNU readline functionality
  and color support, so that IPython under Windows XP/2k can be as friendly
  and powerful as under Unix-like environments.
  
 \layout Standard
 
 This library, now named 
 \family typewriter 
 PyReadline
 \family default 
 , has been absorbed by the IPython team (J�rgen Stenarson, in particular),
  and it continues to be developed with new features, as well as being distribute
 d directly from the IPython site.
 \layout Standard
 
 The
 \family typewriter 
  PyReadline
 \family default 
  extension requires 
 \family typewriter 
 CTypes
 \family default 
  and the windows IPython installer needs 
 \family typewriter 
 PyWin32
 \family default 
 , so in all you need:
 \layout Enumerate
 
 
 \family typewriter 
 PyWin32
 \family default 
  from 
 \begin_inset LatexCommand \htmlurl{http://starship.python.net/crew/mhammond}
 
 \end_inset 
 
 .
 \layout Enumerate
 
 
 \family typewriter 
 CTypes
 \family default 
  from 
 \begin_inset LatexCommand \htmlurl{http://starship.python.net/crew/theller/ctypes}
 
 \end_inset 
 
  (you 
 \emph on 
 must
 \emph default 
  use version 0.9.1 or newer).
 \layout Enumerate
 
 
 \family typewriter 
 PyReadline
 \family default 
  for Windows from 
 \begin_inset LatexCommand \htmlurl{http://projects.scipy.org/ipython/ipython/wiki/PyReadline/Intro}
 
 \end_inset 
 
 .
  That page contains further details on using and configuring the system
  to your liking.
 \layout Standard
 
 
 \series bold 
 Warning about a broken readline-like library:
 \series default 
  several users have reported problems stemming from using the pseudo-readline
  library at 
 \begin_inset LatexCommand \htmlurl{http://newcenturycomputers.net/projects/readline.html}
 
 \end_inset 
 
 .
  This is a broken library which, while called readline, only implements
  an incomplete subset of the readline API.
  Since it is still called readline, it fools IPython's detection mechanisms
  and causes unpredictable crashes later.
  If you wish to use IPython under Windows, you must NOT use this library,
  which for all purposes is (at least as of version 1.6) terminally broken.
 \layout Subsubsection
 
 Installation procedure
 \layout Standard
 
 Once you have the above installed, from the IPython download directory grab
  the 
 \family typewriter 
 ipython-XXX.win32.exe
 \family default 
  file, where 
 \family typewriter 
 XXX
 \family default 
  represents the version number.
  This is a regular windows executable installer, which you can simply double-cli
 ck to install.
  It will add an entry for IPython to your Start Menu, as well as registering
  IPython in the Windows list of applications, so you can later uninstall
  it from the Control Panel.
  
 \layout Standard
 
 IPython tries to install the configuration information in a directory named
  
 \family typewriter 
 .ipython
 \family default 
  (
 \family typewriter 
 _ipython
 \family default 
  under Windows) located in your `home' directory.
  IPython sets this directory by looking for a 
 \family typewriter 
 HOME
 \family default 
  environment variable; if such a variable does not exist, it uses 
 \family typewriter 
 HOMEDRIVE
 \backslash 
 HOMEPATH 
 \family default 
 (these are always defined by Windows).
  This typically gives something like 
 \family typewriter 
 C:
 \backslash 
 Documents and Settings
 \backslash 
 YourUserName
 \family default 
 , but your local details may vary.
  In this directory you will find all the files that configure IPython's
  defaults, and you can put there your profiles and extensions.
  This directory is automatically added by IPython to 
 \family typewriter 
 sys.path
 \family default 
 , so anything you place there can be found by 
 \family typewriter 
 import
 \family default 
  statements.
 \layout Paragraph
 
 Upgrading
 \layout Standard
 
 For an IPython upgrade, you should first uninstall the previous version.
  This will ensure that all files and directories (such as the documentation)
  which carry embedded version strings in their names are properly removed.
 \layout Paragraph
 
 Manual installation under Win32
 \layout Standard
 
 In case the automatic installer does not work for some reason, you can download
  the 
 \family typewriter 
 ipython-XXX.tar.gz
 \family default 
  file, which contains the full IPython source distribution (the popular
  WinZip can read 
 \family typewriter 
 .tar.gz
 \family default 
  files).
  After uncompressing the archive, you can install it at a command terminal
  just like any other Python module, by using 
 \family typewriter 
 `python setup.py install'
 \family default 
 .
  
 \layout Standard
 
 After the installation, run the supplied 
 \family typewriter 
 win32_manual_post_install.py 
 \family default 
 script, which creates the necessary Start Menu shortcuts for you.
 \layout Subsection
 
 
 \begin_inset LatexCommand \label{sec:upgrade}
 
 \end_inset 
 
 Upgrading from a previous version
 \layout Standard
 
 If you are upgrading from a previous version of IPython, after doing the
  routine installation described above, you should call IPython with the
  
 \family typewriter 
 -upgrade
 \family default 
  option the first time you run your new copy.
  This will automatically update your configuration directory while preserving
  copies of your old files.
  You can then later merge back any personal customizations you may have
  made into the new files.
  It is a good idea to do this as there may be new options available in the
  new configuration files which you will not have.
 \layout Standard
 
 Under Windows, if you don't know how to call python scripts with arguments
  from a command line, simply delete the old config directory and IPython
  will make a new one.
  Win2k and WinXP users will find it in 
 \family typewriter 
 C:
 \backslash 
 Documents and Settings
 \backslash 
 YourUserName
 \backslash 
 _ipython
 \family default 
 , and Win 9x users under 
 \family typewriter 
 C:
 \backslash 
 Program Files
 \backslash 
 IPython
 \backslash 
 _ipython.
 \layout Section
 
 
 \begin_inset LatexCommand \label{sec:good_config}
 
 \end_inset 
 
 
 \begin_inset OptArg
 collapsed true
 
 \layout Standard
 
 Initial configuration
 \begin_inset ERT
 status Collapsed
 
 \layout Standard
 
 \backslash 
 ldots
 \end_inset 
 
 
 \end_inset 
 
 Initial configuration of your environment
 \layout Standard
 
 This section will help you set various things in your environment for your
  IPython sessions to be as efficient as possible.
  All of IPython's configuration information, along with several example
  files, is stored in a directory named by default 
 \family typewriter 
 $HOME/.ipython
 \family default 
 .
  You can change this by defining the environment variable 
 \family typewriter 
 IPYTHONDIR
 \family default 
 , or at runtime with the command line option 
 \family typewriter 
 -ipythondir
 \family default 
 .
 \layout Standard
 
 If all goes well, the first time you run IPython it should automatically
  create a user copy of the config directory for you, based on its builtin
  defaults.
  You can look at the files it creates to learn more about configuring the
  system.
  The main file you will modify to configure IPython's behavior is called
  
 \family typewriter 
 ipythonrc
 \family default 
  (with a 
 \family typewriter 
 .ini
 \family default 
  extension under Windows), included for reference in Sec.
  
 \begin_inset LatexCommand \ref{sec:ipytonrc-sample}
 
 \end_inset 
 
 .
  This file is very commented and has many variables you can change to suit
  your taste, you can find more details in Sec.
  
 \begin_inset LatexCommand \ref{sec:customization}
 
 \end_inset 
 
 .
  Here we discuss the basic things you will want to make sure things are
  working properly from the beginning.
 \layout Subsection
 
 
 \begin_inset LatexCommand \label{sec:help-access}
 
 \end_inset 
 
 Access to the Python help system
 \layout Standard
 
 This is true for Python in general (not just for IPython): you should have
  an environment variable called 
 \family typewriter 
 PYTHONDOCS
 \family default 
  pointing to the directory where your HTML Python documentation lives.
  In my system it's 
 \family typewriter 
 /usr/share/doc/python-docs-2.3.4/html
 \family default 
 , check your local details or ask your systems administrator.
  
 \layout Standard
 
 This is the directory which holds the HTML version of the Python manuals.
  Unfortunately it seems that different Linux distributions package these
  files differently, so you may have to look around a bit.
  Below I show the contents of this directory on my system for reference:
 \layout Standard
 
 
 \family typewriter 
 [html]> ls
 \newline 
 about.dat acks.html dist/ ext/ index.html lib/ modindex.html stdabout.dat tut/
  about.html api/ doc/ icons/ inst/ mac/ ref/ style.css
 \layout Standard
 
 You should really make sure this variable is correctly set so that Python's
  pydoc-based help system works.
  It is a powerful and convenient system with full access to the Python manuals
  and all modules accessible to you.
 \layout Standard
 
 Under Windows it seems that pydoc finds the documentation automatically,
  so no extra setup appears necessary.
 \layout Subsection
 
 Editor
 \layout Standard
 
 The 
 \family typewriter 
 %edit
 \family default 
  command (and its alias 
 \family typewriter 
 %ed
 \family default 
 ) will invoke the editor set in your environment as 
 \family typewriter 
 EDITOR
 \family default 
 .
  If this variable is not set, it will default to 
 \family typewriter 
 vi
 \family default 
  under Linux/Unix and to 
 \family typewriter 
 notepad
 \family default 
  under Windows.
  You may want to set this variable properly and to a lightweight editor
  which doesn't take too long to start (that is, something other than a new
  instance of 
 \family typewriter 
 Emacs
 \family default 
 ).
  This way you can edit multi-line code quickly and with the power of a real
  editor right inside IPython.
  
 \layout Standard
 
 If you are a dedicated 
 \family typewriter 
 Emacs
 \family default 
  user, you should set up the 
 \family typewriter 
 Emacs
 \family default 
  server so that new requests are handled by the original process.
  This means that almost no time is spent in handling the request (assuming
  an 
 \family typewriter 
 Emacs
 \family default 
  process is already running).
  For this to work, you need to set your 
 \family typewriter 
 EDITOR 
 \family default 
 environment variable to 
 \family typewriter 
 'emacsclient'
 \family default 
 .
 
 \family typewriter 
  
 \family default 
 The code below, supplied by Francois Pinard, can then be used in your 
 \family typewriter 
 .emacs
 \family default 
  file to enable the server:
 \layout Standard
 
 
 \family typewriter 
 (defvar server-buffer-clients)
 \newline 
 (when (and (fboundp 'server-start) (string-equal (getenv "TERM") 'xterm))
 \newline 
 
 \begin_inset ERT
 status Collapsed
 
 \layout Standard
 
 \backslash 
 hspace*{0mm}
 \end_inset 
 
 \SpecialChar ~
 \SpecialChar ~
 (server-start)
 \newline 
 
 \begin_inset ERT
 status Collapsed
 
 \layout Standard
 
 \backslash 
 hspace*{0mm}
 \end_inset 
 
 \SpecialChar ~
 \SpecialChar ~
 (defun fp-kill-server-with-buffer-routine ()
 \newline 
 
 \begin_inset ERT
 status Collapsed
 
 \layout Standard
 
 \backslash 
 hspace*{0mm}
 \end_inset 
 
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 (and server-buffer-clients (server-done)))
 \newline 
 
 \begin_inset ERT
 status Collapsed
 
 \layout Standard
 
 \backslash 
 hspace*{0mm}
 \end_inset 
 
 \SpecialChar ~
 \SpecialChar ~
 (add-hook 'kill-buffer-hook 'fp-kill-server-with-buffer-routine))
 \layout Standard
 
 You can also set the value of this editor via the commmand-line option '-
 \family typewriter 
 editor'
 \family default 
  or in your 
 \family typewriter 
 ipythonrc
 \family default 
  file.
  This is useful if you wish to use specifically for IPython an editor different
  from your typical default (and for Windows users who tend to use fewer
  environment variables).
 \layout Subsection
 
 Color 
 \layout Standard
 
 The default IPython configuration has most bells and whistles turned on
  (they're pretty safe).
  But there's one that 
 \emph on 
 may
 \emph default 
  cause problems on some systems: the use of color on screen for displaying
  information.
  This is very useful, since IPython can show prompts and exception tracebacks
  with various colors, display syntax-highlighted source code, and in general
  make it easier to visually parse information.
 \layout Standard
 
 The following terminals seem to handle the color sequences fine:
 \layout Itemize
 
 Linux main text console, KDE Konsole, Gnome Terminal, E-term, rxvt, xterm.
 \layout Itemize
 
 CDE terminal (tested under Solaris).
  This one boldfaces light colors.
 \layout Itemize
 
 (X)Emacs buffers.
  See sec.
 \begin_inset LatexCommand \ref{sec:emacs}
 
 \end_inset 
 
  for more details on using IPython with (X)Emacs.
 \layout Itemize
 
 A Windows (XP/2k) command prompt 
 \emph on 
 with Gary Bishop's support extensions
 \emph default 
 .
  Gary's extensions are discussed in Sec.\SpecialChar ~
 
 \begin_inset LatexCommand \ref{sub:Under-Windows}
 
 \end_inset 
 
 .
 \layout Itemize
 
 A Windows (XP/2k) CygWin shell.
  Although some users have reported problems; it is not clear whether there
  is an issue for everyone or only under specific configurations.
  If you have full color support under cygwin, please post to the IPython
  mailing list so this issue can be resolved for all users.
 \layout Standard
 
 These have shown problems:
 \layout Itemize
 
 Windows command prompt in WinXP/2k logged into a Linux machine via telnet
  or ssh.
 \layout Itemize
 
 Windows native command prompt in WinXP/2k, 
 \emph on 
 without 
 \emph default 
 Gary Bishop's extensions.
  Once Gary's readline library is installed, the normal WinXP/2k command
  prompt works perfectly.
 \layout Standard
 
 Currently the following color schemes are available:
 \layout Itemize
 
 
 \family typewriter 
 NoColor
 \family default 
 : uses no color escapes at all (all escapes are empty 
 \begin_inset Quotes eld
 \end_inset 
 
  
 \begin_inset Quotes eld
 \end_inset 
 
  strings).
  This 'scheme' is thus fully safe to use in any terminal.
 \layout Itemize
 
 
 \family typewriter 
 Linux
 \family default 
 : works well in Linux console type environments: dark background with light
  fonts.
  It uses bright colors for information, so it is difficult to read if you
  have a light colored background.
 \layout Itemize
 
 
 \family typewriter 
 LightBG
 \family default 
 : the basic colors are similar to those in the 
 \family typewriter 
 Linux
 \family default 
  scheme but darker.
  It is easy to read in terminals with light backgrounds.
 \layout Standard
 
 IPython uses colors for two main groups of things: prompts and tracebacks
  which are directly printed to the terminal, and the object introspection
  system which passes large sets of data through a pager.
 \layout Subsubsection
 
 Input/Output prompts and exception tracebacks
 \layout Standard
 
 You can test whether the colored prompts and tracebacks work on your system
  interactively by typing 
 \family typewriter 
 '%colors Linux'
 \family default 
  at the prompt (use '
 \family typewriter 
 %colors LightBG'
 \family default 
  if your terminal has a light background).
  If the input prompt shows garbage like:
 \newline 
 
 \family typewriter 
 [0;32mIn [[1;32m1[0;32m]: [0;00m
 \family default 
 
 \newline 
 instead of (in color) something like:
 \newline 
 
 \family typewriter 
 In [1]:
 \family default 
  
 \newline 
 this means that your terminal doesn't properly handle color escape sequences.
  You can go to a 'no color' mode by typing '
 \family typewriter 
 %colors NoColor
 \family default 
 '.
  
 \layout Standard
 
 You can try using a different terminal emulator program (Emacs users, see
  below).
  To permanently set your color preferences, edit the file
 \family typewriter 
  $HOME/.ipython/ipythonrc 
 \family default 
 and set the 
 \family typewriter 
 colors
 \family default 
  option to the desired value.
 \layout Subsubsection
 
 Object details (types, docstrings, source code, etc.)
 \layout Standard
 
 IPython has a set of special functions for studying the objects you are
  working with, discussed in detail in Sec.
  
 \begin_inset LatexCommand \ref{sec:dyn-object-info}
 
 \end_inset 
 
 .
  But this system relies on passing information which is longer than your
  screen through a data pager, such as the common Unix 
 \family typewriter 
 less
 \family default 
  and 
 \family typewriter 
 more
 \family default 
  programs.
  In order to be able to see this information in color, your pager needs
  to be properly configured.
  I strongly recommend using 
 \family typewriter 
 less
 \family default 
  instead of 
 \family typewriter 
 more
 \family default 
 , as it seems that 
 \family typewriter 
 more
 \family default 
  simply can not understand colored text correctly.
 \layout Standard
 
 In order to configure 
 \family typewriter 
 less
 \family default 
  as your default pager, do the following:
 \layout Enumerate
 
 Set the environment 
 \family typewriter 
 PAGER
 \family default 
  variable to 
 \family typewriter 
 less
 \family default 
 .
 \layout Enumerate
 
 Set the environment 
 \family typewriter 
 LESS
 \family default 
  variable to 
 \family typewriter 
 -r
 \family default 
  (plus any other options you always want to pass to 
 \family typewriter 
 less
 \family default 
  by default).
  This tells 
 \family typewriter 
 less
 \family default 
  to properly interpret control sequences, which is how color information
  is given to your terminal.
 \layout Standard
 
 For the 
 \family typewriter 
 csh
 \family default 
  or 
 \family typewriter 
 tcsh
 \family default 
  shells, add to your 
 \family typewriter 
 ~/.cshrc
 \family default 
  file the lines:
 \layout Standard
 
 
 \family typewriter 
 setenv PAGER less
 \newline 
 setenv LESS -r
 \layout Standard
 
 There is similar syntax for other Unix shells, look at your system documentation
  for details.
 \layout Standard
 
 If you are on a system which lacks proper data pagers (such as Windows),
  IPython will use a very limited builtin pager.
 \layout Subsection
 
 
 \begin_inset LatexCommand \label{sec:emacs}
 
 \end_inset 
 
 (X)Emacs configuration
 \layout Standard
 
 Thanks to the work of Alexander Schmolck and Prabhu Ramachandran, currently
  (X)Emacs and IPython get along very well.
  
 \layout Standard
 
 
 \series bold 
 Important note:
 \series default 
  You will need to use a recent enough version of 
 \family typewriter 
 python-mode.el
 \family default 
 , along with the file 
 \family typewriter 
 ipython.el
 \family default 
 .
  You can check that the version you have of 
 \family typewriter 
 python-mode.el
 \family default 
  is new enough by either looking at the revision number in the file itself,
  or asking for it in (X)Emacs via 
 \family typewriter 
 M-x py-version
 \family default 
 .
  Versions 4.68 and newer contain the necessary fixes for proper IPython support.
 \layout Standard
 
 The file 
 \family typewriter 
 ipython.el
 \family default 
  is included with the IPython distribution, in the documentation directory
  (where this manual resides in PDF and HTML formats).
 \layout Standard
 
 Once you put these files in your Emacs path, all you need in your 
 \family typewriter 
 .emacs
 \family default 
  file is:
 \layout LyX-Code
 
 (require 'ipython)
 \layout Standard
 
 This should give you full support for executing code snippets via IPython,
  opening IPython as your Python shell via 
 \family typewriter 
 C-c\SpecialChar ~
 !
 \family default 
 , etc.
  
 \layout Standard
 
 If you happen to get garbage instead of colored prompts as described in
  the previous section, you may need to set also in your 
 \family typewriter 
 .emacs
 \family default 
  file:
 \layout LyX-Code
 
 (setq ansi-color-for-comint-mode t)
 \layout Subsubsection*
 
 Notes
 \layout Itemize
 
 There is one caveat you should be aware of: you must start the IPython shell
  
 \emph on 
 before
 \emph default 
  attempting to execute any code regions via 
 \family typewriter 
 C-c\SpecialChar ~
 |
 \family default 
 .
  Simply type 
 \family typewriter 
 C-c\SpecialChar ~
 !
 \family default 
  to start IPython before passing any code regions to the interpreter, and
  you shouldn't experience any problems.
 \newline 
 This is due to a bug in Python itself, which has been fixed for Python 2.3,
  but exists as of Python 2.2.2 (reported as SF bug [ 737947 ]).
 \layout Itemize
 
 The (X)Emacs support is maintained by Alexander Schmolck, so all comments/reques
 ts should be directed to him through the IPython mailing lists.
  
 \layout Itemize
 
 This code is still somewhat experimental so it's a bit rough around the
  edges (although in practice, it works quite well).
 \layout Itemize
 
 Be aware that if you customize 
 \family typewriter 
 py-python-command
 \family default 
  previously, this value will override what 
 \family typewriter 
 ipython.el
 \family default 
  does (because loading the customization variables comes later).
 \layout Section
 
 
 \begin_inset LatexCommand \label{sec:quick_tips}
 
 \end_inset 
 
 Quick tips
 \layout Standard
 
 IPython can be used as an improved replacement for the Python prompt, and
  for that you don't really need to read any more of this manual.
  But in this section we'll try to summarize a few tips on how to make the
  most effective use of it for everyday Python development, highlighting
  things you might miss in the rest of the manual (which is getting long).
  We'll give references to parts in the manual which provide more detail
  when appropriate.
 \layout Standard
 
 The following article by Jeremy Jones provides an introductory tutorial
  about IPython:
 \newline 
 
 \begin_inset LatexCommand \htmlurl{http://www.onlamp.com/pub/a/python/2005/01/27/ipython.html}
 
 \end_inset 
 
 
 \layout Itemize
 
 The TAB key.
  TAB-completion, especially for attributes, is a convenient way to explore
  the structure of any object you're dealing with.
  Simply type 
 \family typewriter 
 object_name.<TAB>
 \family default 
  and a list of the object's attributes will be printed (see sec.
  
 \begin_inset LatexCommand \ref{sec:readline}
 
 \end_inset 
 
  for more).
  Tab completion also works on file and directory names, which combined with
  IPython's alias system allows you to do from within IPython many of the
  things you normally would need the system shell for.
  
 \layout Itemize
 
 Explore your objects.
  Typing 
 \family typewriter 
 object_name?
 \family default 
  will print all sorts of details about any object, including docstrings,
  function definition lines (for call arguments) and constructor details
  for classes.
  The magic commands 
 \family typewriter 
 %pdoc
 \family default 
 , 
 \family typewriter 
 %pdef
 \family default 
 , 
 \family typewriter 
 %psource
 \family default 
  and 
 \family typewriter 
 %pfile
 \family default 
  will respectively print the docstring, function definition line, full source
  code and the complete file for any object (when they can be found).
  If automagic is on (it is by default), you don't need to type the '
 \family typewriter 
 %
 \family default 
 ' explicitly.
  See sec.
  
 \begin_inset LatexCommand \ref{sec:dyn-object-info}
 
 \end_inset 
 
  for more.
 \layout Itemize
 
 The 
 \family typewriter 
 %run
 \family default 
  magic command allows you to run any python script and load all of its data
  directly into the interactive namespace.
  Since the file is re-read from disk each time, changes you make to it are
  reflected immediately (in contrast to the behavior of 
 \family typewriter 
 import
 \family default 
 ).
  I rarely use 
 \family typewriter 
 import
 \family default 
  for code I am testing, relying on 
 \family typewriter 
 %run
 \family default 
  instead.
  See sec.
  
 \begin_inset LatexCommand \ref{sec:magic}
 
 \end_inset 
 
  for more on this and other magic commands, or type the name of any magic
  command and ? to get details on it.
  See also sec.
  
 \begin_inset LatexCommand \ref{sec:dreload}
 
 \end_inset 
 
  for a recursive reload command.
 \newline 
 
 \family typewriter 
 %run
 \family default 
  also has special flags for timing the execution of your scripts (
 \family typewriter 
 -t
 \family default 
 ) and for executing them under the control of either Python's 
 \family typewriter 
 pdb 
 \family default 
 debugger (
 \family typewriter 
 -d
 \family default 
 ) or profiler (
 \family typewriter 
 -p
 \family default 
 ).
  With all of these, 
 \family typewriter 
 %run
 \family default 
  can be used as the main tool for efficient interactive development of code
  which you write in your editor of choice.
 \layout Itemize
 
 Use the Python debugger, 
 \family typewriter 
 pdb
 \family default 
 
 \begin_inset Foot
 collapsed true
 
 \layout Standard
 
 Thanks to Christian Hart and Matthew Arnison for the suggestions leading
  to IPython's improved debugger and profiler support.
 \end_inset 
 
 .
  The 
 \family typewriter 
 %pdb
 \family default 
  command allows you to toggle on and off the automatic invocation of an
  IPython-enhanced 
 \family typewriter 
 pdb
 \family default 
  debugger (with coloring, tab completion and more) at any uncaught exception.
  The advantage of this is that 
 \family typewriter 
 pdb
 \family default 
  starts 
 \emph on 
 inside
 \emph default 
  the function where the exception occurred, with all data still available.
  You can print variables, see code, execute statements and even walk up
  and down the call stack to track down the true source of the problem (which
  often is many layers in the stack above where the exception gets triggered).
 \newline 
 Running programs with 
 \family typewriter 
 %run
 \family default 
  and pdb active can be an efficient to develop and debug code, in many cases
  eliminating the need for 
 \family typewriter 
 print
 \family default 
  statements or external debugging tools.
  I often simply put a 
 \family typewriter 
 1/0
 \family default 
  in a place where I want to take a look so that pdb gets called, quickly
  view whatever variables I need to or test various pieces of code and then
  remove the 
 \family typewriter 
 1/0
 \family default 
 .
 \newline 
 Note also that `
 \family typewriter 
 %run -d
 \family default 
 ' activates 
 \family typewriter 
 pdb
 \family default 
  and automatically sets initial breakpoints for you to step through your
  code, watch variables, etc.
  See Sec.\SpecialChar ~
 
 \begin_inset LatexCommand \ref{sec:cache_output}
 
 \end_inset 
 
  for details.
 \layout Itemize
 
 Use the output cache.
  All output results are automatically stored in a global dictionary named
  
 \family typewriter 
 Out
 \family default 
  and variables named 
 \family typewriter 
 _1
 \family default 
 , 
 \family typewriter 
 _2
 \family default 
 , etc.
  alias them.
  For example, the result of input line 4 is available either as 
 \family typewriter 
 Out[4]
 \family default 
  or as 
 \family typewriter 
 _4
 \family default 
 .
  Additionally, three variables named 
 \family typewriter 
 _
 \family default 
 , 
 \family typewriter 
 __
 \family default 
  and 
 \family typewriter 
 ___
 \family default 
  are always kept updated with the for the last three results.
  This allows you to recall any previous result and further use it for new
  calculations.
  See Sec.\SpecialChar ~
 
 \begin_inset LatexCommand \ref{sec:cache_output}
 
 \end_inset 
 
  for more.
 \layout Itemize
 
 Put a '
 \family typewriter 
 ;
 \family default 
 ' at the end of a line to supress the printing of output.
  This is useful when doing calculations which generate long output you are
  not interested in seeing.
  The 
 \family typewriter 
 _*
 \family default 
  variables and the 
 \family typewriter 
 Out[]
 \family default 
  list do get updated with the contents of the output, even if it is not
  printed.
  You can thus still access the generated results this way for further processing.
 \layout Itemize
 
 A similar system exists for caching input.
  All input is stored in a global list called 
 \family typewriter 
 In
 \family default 
  , so you can re-execute lines 22 through 28 plus line 34 by typing 
 \family typewriter 
 'exec In[22:29]+In[34]'
 \family default 
  (using Python slicing notation).
  If you need to execute the same set of lines often, you can assign them
  to a macro with the 
 \family typewriter 
 %macro
 \family default 
  
 \family typewriter 
 function.
  
 \family default 
 See sec.
  
 \begin_inset LatexCommand \ref{sec:cache_input}
 
 \end_inset 
 
  for more.
 \layout Itemize
 
 Use your input history.
  The 
 \family typewriter 
 %hist
 \family default 
  command can show you all previous input, without line numbers if desired
  (option 
 \family typewriter 
 -n
 \family default 
 ) so you can directly copy and paste code either back in IPython or in a
  text editor.
  You can also save all your history by turning on logging via 
 \family typewriter 
 %logstart
 \family default 
 ; these logs can later be either reloaded as IPython sessions or used as
  code for your programs.
 \layout Itemize
 
 Define your own system aliases.
  Even though IPython gives you access to your system shell via the 
 \family typewriter 
 !
 \family default 
  prefix, it is convenient to have aliases to the system commands you use
  most often.
  This allows you to work seamlessly from inside IPython with the same commands
  you are used to in your system shell.
 \newline 
 IPython comes with some pre-defined aliases and a complete system for changing
  directories, both via a stack (see 
 \family typewriter 
 %pushd
 \family default 
 , 
 \family typewriter 
 %popd
 \family default 
  and 
 \family typewriter 
 %dhist
 \family default 
 ) and via direct 
 \family typewriter 
 %cd
 \family default 
 .
  The latter keeps a history of visited directories and allows you to go
  to any previously visited one.
 \layout Itemize
 
 Use Python to manipulate the results of system commands.
  The `
 \family typewriter 
 !!
 \family default 
 ' special syntax, and the 
 \family typewriter 
 %sc
 \family default 
  and 
 \family typewriter 
 %sx
 \family default 
  magic commands allow you to capture system output into Python variables.
 \layout Itemize
 
 Expand python variables when calling the shell (either via 
 \family typewriter 
 `!'
 \family default 
  and 
 \family typewriter 
 `!!'
 \family default 
  or via aliases) by prepending a 
 \family typewriter 
 $
 \family default 
  in front of them.
  You can also expand complete python expressions.
  See sec.\SpecialChar ~
 
 \begin_inset LatexCommand \ref{sub:System-shell-access}
 
 \end_inset 
 
  for more.
 \layout Itemize
 
 Use profiles to maintain different configurations (modules to load, function
  definitions, option settings) for particular tasks.
  You can then have customized versions of IPython for specific purposes.
  See sec.\SpecialChar ~
 
 \begin_inset LatexCommand \ref{sec:profiles}
 
 \end_inset 
 
  for more.
 \layout Itemize
 
 Embed IPython in your programs.
  A few lines of code are enough to load a complete IPython inside your own
  programs, giving you the ability to work with your data interactively after
  automatic processing has been completed.
  See sec.\SpecialChar ~
 
 \begin_inset LatexCommand \ref{sec:embed}
 
 \end_inset 
 
  for more.
 \layout Itemize
 
 Use the Python profiler.
  When dealing with performance issues, the 
 \family typewriter 
 %run
 \family default 
  command with a 
 \family typewriter 
 -p
 \family default 
  option allows you to run complete programs under the control of the Python
  profiler.
  The 
 \family typewriter 
 %prun
 \family default 
  command does a similar job for single Python expressions (like function
  calls).
 \layout Itemize
 
 Use the IPython.demo.Demo class to load any Python script as an interactive
  demo.
  With a minimal amount of simple markup, you can control the execution of
  the script, stopping as needed.
  See sec.\SpecialChar ~
 
 \begin_inset LatexCommand \ref{sec:interactive-demos}
 
 \end_inset 
 
  for more.
 \layout Subsection
 
 Source code handling tips
 \layout Standard
 
 IPython is a line-oriented program, without full control of the terminal.
  Therefore, it doesn't support true multiline editing.
  However, it has a number of useful tools to help you in dealing effectively
  with more complex editing.
 \layout Standard
 
 The 
 \family typewriter 
 %edit
 \family default 
  command gives a reasonable approximation of multiline editing, by invoking
  your favorite editor on the spot.
  IPython will execute the code you type in there as if it were typed interactive
 ly.
  Type 
 \family typewriter 
 %edit?
 \family default 
  for the full details on the edit command.
 \layout Standard
 
 If you have typed various commands during a session, which you'd like to
  reuse, IPython provides you with a number of tools.
  Start by using 
 \family typewriter 
 %hist
 \family default 
  to see your input history, so you can see the line numbers of all input.
  Let us say that you'd like to reuse lines 10 through 20, plus lines 24
  and 28.
  All the commands below can operate on these with the syntax
 \layout LyX-Code
 
 %command 10-20 24 28
 \layout Standard
 
 where the command given can be:
 \layout Itemize
 
 
 \family typewriter 
 %macro <macroname>
 \family default 
 : this stores the lines into a variable which, when called at the prompt,
  re-executes the input.
  Macros can be edited later using 
 \family typewriter 
 `%edit macroname
 \family default 
 ', and they can be stored persistently across sessions with `
 \family typewriter 
 %store macroname
 \family default 
 ' (the storage system is per-profile).
  The combination of quick macros, persistent storage and editing, allows
  you to easily refine quick-and-dirty interactive input into permanent utilities
 , always available both in IPython and as files for general reuse.
 \layout Itemize
 
 
 \family typewriter 
 %edit
 \family default 
 : this will open a text editor with those lines pre-loaded for further modificat
 ion.
  It will then execute the resulting file's contents as if you had typed
  it at the prompt.
 \layout Itemize
 
 
 \family typewriter 
 %save <filename>
 \family default 
 : this saves the lines directly to a named file on disk.
 \layout Standard
 
 While 
 \family typewriter 
 %macro
 \family default 
  saves input lines into memory for interactive re-execution, sometimes you'd
  like to save your input directly to a file.
  The 
 \family typewriter 
 %save
 \family default 
  magic does this: its input sytnax is the same as 
 \family typewriter 
 %macro
 \family default 
 , but it saves your input directly to a Python file.
  Note that the 
 \family typewriter 
 %logstart
 \family default 
  command also saves input, but it logs 
 \emph on 
 all
 \emph default 
  input to disk (though you can temporarily suspend it and reactivate it
  with 
 \family typewriter 
 %logoff/%logon
 \family default 
 ); 
 \family typewriter 
 %save
 \family default 
  allows you to select which lines of input you need to save.
 \layout Subsubsection*
 
 Lightweight 'version control'
 \layout Standard
 
 When you call 
 \family typewriter 
 %edit
 \family default 
  with no arguments, IPython opens an empty editor with a temporary file,
  and it returns the contents of your editing session as a string variable.
  Thanks to IPython's output caching mechanism, this is automatically stored:
 \layout LyX-Code
 
 In [1]: %edit
 \layout LyX-Code
 
 IPython will make a temporary file named: /tmp/ipython_edit_yR-HCN.py
 \layout LyX-Code
 
 Editing...
  done.
  Executing edited code...
 \layout LyX-Code
 
 hello - this is a temporary file
 \layout LyX-Code
 
 Out[1]: "print 'hello - this is a temporary file'
 \backslash 
 n"
 \layout Standard
 
 Now, if you call 
 \family typewriter 
 `%edit -p'
 \family default 
 , IPython tries to open an editor with the same data as the last time you
  used 
 \family typewriter 
 %edit
 \family default 
 .
  So if you haven't used 
 \family typewriter 
 %edit
 \family default 
  in the meantime, this same contents will reopen; however, it will be done
  in a 
 \emph on 
 new file
 \emph default 
 .
  This means that if you make changes and you later want to find an old version,
  you can always retrieve it by using its output number, via 
 \family typewriter 
 `%edit _NN'
 \family default 
 , where 
 \family typewriter 
 NN
 \family default 
  is the number of the output prompt.
 \layout Standard
 
 Continuing with the example above, this should illustrate this idea:
 \layout LyX-Code
 
 In [2]: edit -p
 \layout LyX-Code
 
 IPython will make a temporary file named: /tmp/ipython_edit_nA09Qk.py
 \layout LyX-Code
 
 Editing...
  done.
  Executing edited code...
 \layout LyX-Code
 
 hello - now I made some changes
 \layout LyX-Code
 
 Out[2]: "print 'hello - now I made some changes'
 \backslash 
 n"
 \layout LyX-Code
 
 In [3]: edit _1
 \layout LyX-Code
 
 IPython will make a temporary file named: /tmp/ipython_edit_gy6-zD.py
 \layout LyX-Code
 
 Editing...
  done.
  Executing edited code...
 \layout LyX-Code
 
 hello - this is a temporary file
 \layout LyX-Code
 
 IPython version control at work :)
 \layout LyX-Code
 
 Out[3]: "print 'hello - this is a temporary file'
 \backslash 
 nprint 'IPython version control at work :)'
 \backslash 
 n"
 \layout Standard
 
 This section was written after a contribution by Alexander Belchenko on
  the IPython user list.
 \layout LyX-Code
 
 \layout Subsection
 
 Effective logging
 \layout Standard
 
 A very useful suggestion sent in by Robert Kern follows:
 \layout Standard
 
 I recently happened on a nifty way to keep tidy per-project log files.
  I made a profile for my project (which is called "parkfield").
 \layout LyX-Code
 
 include ipythonrc
 \layout LyX-Code
 
 # cancel earlier logfile invocation:
 \layout LyX-Code
 
 logfile ''
 \layout LyX-Code
 
 execute import time
 \layout LyX-Code
 
 execute __cmd = '/Users/kern/research/logfiles/parkfield-%s.log rotate'
 \layout LyX-Code
 
 execute __IP.magic_logstart(__cmd % time.strftime('%Y-%m-%d'))
 \layout Standard
 
 I also added a shell alias for convenience:
 \layout LyX-Code
 
 alias parkfield="ipython -pylab -profile parkfield"
 \layout Standard
 
 Now I have a nice little directory with everything I ever type in, organized
  by project and date.
 \layout Standard
 
 
 \series bold 
 Contribute your own: 
 \series default 
 If you have your own favorite tip on using IPython efficiently for a certain
  task (especially things which can't be done in the normal Python interpreter),
  don't hesitate to send it!
 \layout Section
 
 Command-line use
 \layout Standard
 
 You start IPython with the command:
 \layout Standard
 
 
 \family typewriter 
 $ ipython [options] files
 \layout Standard
 
 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 
 \family typewriter 
 python -i
 \family default 
  will only execute one file and ignore your configuration setup.
 \layout Standard
 
 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 
 \family typewriter 
 $HOME/.ipython
 \family default 
  directory.
  For Windows users, 
 \family typewriter 
 $HOME
 \family default 
  resolves to 
 \family typewriter 
 C:
 \backslash 
 
 \backslash 
 Documents and Settings
 \backslash 
 
 \backslash 
 YourUserName
 \family default 
  in most instances.
  In the rest of this text, we will refer to this directory as 
 \family typewriter 
 IPYTHONDIR
 \family default 
 .
 \layout Subsection
 
 
 \begin_inset LatexCommand \label{sec:threading-opts}
 
 \end_inset 
 
 Special Threading Options
 \layout Standard
 
 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.
 \layout List
 \labelwidthstring 00.00.0000
 
 
 \family typewriter 
 \series bold 
 -gthread,\SpecialChar ~
 -qthread,\SpecialChar ~
 -wthread,\SpecialChar ~
 -pylab:
 \family default 
 \series default 
  Only 
 \emph on 
 one
 \emph default 
  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 WXPython toolkits, and
  for the matplotlib library.
 \layout List
 \labelwidthstring 00.00.0000
 
 \SpecialChar ~
  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).
 \layout List
 \labelwidthstring 00.00.0000
 
 \SpecialChar ~
  Note that with 
 \family typewriter 
 -wthread
 \family default 
 , you can additionally use the -wxversion option to request a specific version
  of wx to be used.
  This requires that you have the 
 \family typewriter 
 wxversion
 \family default 
  Python module installed, which is part of recent wxPython distributions.
 \layout List
 \labelwidthstring 00.00.0000
 
 \SpecialChar ~
  If 
 \family typewriter 
 -pylab
 \family default 
  is given, IPython loads special support for the mat plotlib library (
 \begin_inset LatexCommand \htmlurl{http://matplotlib.sourceforge.net}
 
 \end_inset 
 
 ), allowing interactive usage of any of its backends as defined in the user's
  
 \family typewriter 
 ~/.matplotlib/matplotlibrc
 \family default 
  file.
  It automatically activates GTK, Qt or WX threading for IPyhton if the choice
  of matplotlib backend requires it.
  It also modifies the 
 \family typewriter 
 %run
 \family default 
  command to correctly execute (without blocking) any matplotlib-based script
  which calls 
 \family typewriter 
 show()
 \family default 
  at the end.
  
 \layout List
 \labelwidthstring 00.00.0000
 
 
 \family typewriter 
 \series bold 
 -tk
 \family default 
 \series default 
  The 
 \family typewriter 
 -g/q/wthread
 \family default 
  options, and 
 \family typewriter 
 -pylab
 \family default 
  (if matplotlib is configured to use GTK, Qt or WX), will normally block
  Tk graphical interfaces.
  This means that when either 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, 
 \family typewriter 
 -tk
 \family default 
 , is available to address this issue.
  It can 
 \emph on 
 only
 \emph default 
  be given as a 
 \emph on 
 second
 \emph default 
  option after any of the above (
 \family typewriter 
 -gthread
 \family default 
 , 
 \family typewriter 
 -wthread
 \family default 
  or 
 \family typewriter 
 -pylab
 \family default 
 ).
 \layout List
 \labelwidthstring 00.00.0000
 
 \SpecialChar ~
  If 
 \family typewriter 
 -tk
 \family default 
  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.
 \layout List
 \labelwidthstring 00.00.0000
 
 \SpecialChar ~
  There is unfortunately no way for IPython to determine at run time whether
  
 \family typewriter 
 -tk
 \family default 
  will work reliably or not, so you will need to do some experiments before
  relying on it for regular work.
  
 \layout Subsection
 
 
 \begin_inset LatexCommand \label{sec:cmd-line-opts}
 
 \end_inset 
 
 Regular Options
 \layout Standard
 
 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 
 \family typewriter 
 |
 \family default 
 .
 \layout Standard
 
 Most options can also be set from your ipythonrc configuration file.
  See the provided example for more details on what the options do.
  Options given at the command line override the values set in the ipythonrc
  file.
 \layout Standard
 
 All options with a 
 \family typewriter 
 [no]
 \family default 
  prepended can be specified in negated form (
 \family typewriter 
 -nooption
 \family default 
  instead of 
 \family typewriter 
 -option
 \family default 
 ) to turn the feature off.
 \layout List
 \labelwidthstring 00.00.0000
 
 
 \family typewriter 
 \series bold 
 -help
 \family default 
 \series default 
 : print a help message and exit.
 \layout List
 \labelwidthstring 00.00.0000
 
 
 \family typewriter 
 \series bold 
 -pylab:
 \family default 
 \series default 
  this can 
 \emph on 
 only
 \emph default 
  be given as the 
 \emph on 
 first
 \emph default 
  option passed to IPython (it will have no effect in any other position).
  It adds special support for the matplotlib library (
 \begin_inset LatexCommand \htmlurl[http://matplotlib.sourceforge.net]{http://matplotlib.sourceforge.net}
 
 \end_inset 
 
 ), allowing interactive usage of any of its backends as defined in the user's
  
 \family typewriter 
 .matplotlibrc
 \family default 
  file.
  It automatically activates GTK or WX threading for IPyhton if the choice
  of matplotlib backend requires it.
  It also modifies the 
 \family typewriter 
 %run
 \family default 
  command to correctly execute (without blocking) any matplotlib-based script
  which calls 
 \family typewriter 
 show()
 \family default 
  at the end.
  See Sec.\SpecialChar ~
 
 \begin_inset LatexCommand \ref{sec:matplotlib-support}
 
 \end_inset 
 
  for more details.
 \layout List
 \labelwidthstring 00.00.0000
 
 
 \family typewriter 
 \series bold 
 -autocall <val>:
 \family default 
 \series default 
  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 
 \emph on 
 smart
 \emph default 
  autocall, where it is not applied if there are no more arguments on the
  line, and `2' for 
 \emph on 
 full
 \emph default 
  autocall, where all callable objects are automatically called (even if
  no arguments are present).
  The default is `1'.
 \layout List
 \labelwidthstring 00.00.0000
 
 
 \family typewriter 
 \series bold 
 -[no]autoindent:
 \family default 
 \series default 
  Turn automatic indentation on/off.
 \layout List
 \labelwidthstring 00.00.0000
 
 
 \family typewriter 
 \series bold 
 -[no]automagic
 \series default 
 :
 \family default 
  make magic commands automatic (without needing their first character to
  be 
 \family typewriter 
 %
 \family default 
 ).
  Type 
 \family typewriter 
 %magic
 \family default 
  at the IPython prompt for more information.
 \layout List
 \labelwidthstring 00.00.0000
 
 
 \family typewriter 
 \series bold 
 -[no]autoedit_syntax:
 \family default 
 \series default 
  When a syntax error occurs after editing a file, automatically open the
  file to the trouble causing line for convenient fixing.
  
 \layout List
 \labelwidthstring 00.00.0000
 
 
 \family typewriter 
 \series bold 
 -[no]banner
 \series default 
 :
 \family default 
  Print the initial information banner (default on).
 \layout List
 \labelwidthstring 00.00.0000
 
 
 \family typewriter 
 \series bold 
 -c\SpecialChar ~
 <command>:
 \family default 
 \series default 
  execute the given command string, and set sys.argv to 
 \family typewriter 
 ['c']
 \family default 
 .
  This is similar to the 
 \family typewriter 
 -c
 \family default 
  option in the normal Python interpreter.
  
 \layout List
 \labelwidthstring 00.00.0000
 
 
 \family typewriter 
 \series bold 
 -cache_size|cs\SpecialChar ~
 <n>
 \series default 
 :
 \family default 
  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.
 \layout List
 \labelwidthstring 00.00.0000
 
 
 \family typewriter 
 \series bold 
 -classic|cl
 \series default 
 :
 \family default 
  Gives IPython a similar feel to the classic Python prompt.
 \layout List
 \labelwidthstring 00.00.0000
 
 
 \family typewriter 
 \series bold 
 -colors\SpecialChar ~
 <scheme>:
 \family default 
 \series default 
  Color scheme for prompts and exception reporting.
  Currently implemented: NoColor, Linux and LightBG.
 \layout List
 \labelwidthstring 00.00.0000
 
 
 \family typewriter 
 \series bold 
 -[no]color_info:
 \family default 
 \series default 
  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.
 \layout List
 \labelwidthstring 00.00.0000
 
 \SpecialChar ~
  Test it and turn it on permanently if it works with your system.
  The magic function 
 \family typewriter 
 %color_info
 \family default 
  allows you to toggle this interactively for testing.
 \layout List
 \labelwidthstring 00.00.0000
 
 
 \family typewriter 
 \series bold 
 -[no]debug
 \family default 
 \series default 
 : Show information about the loading process.
  Very useful to pin down problems with your configuration files or to get
  details about session restores.
 \layout List
 \labelwidthstring 00.00.0000
 
 
 \family typewriter 
 \series bold 
 -[no]deep_reload
 \series default 
 :
 \family default 
  IPython can use the 
 \family typewriter 
 deep_reload
 \family default 
  module which reloads changes in modules recursively (it replaces the 
 \family typewriter 
 reload()
 \family default 
  function, so you don't need to change anything to use it).
  
 \family typewriter 
 deep_reload()
 \family default 
  forces a full reload of modules whose code may have changed, which the
  default 
 \family typewriter 
 reload()
 \family default 
  function does not.
 \layout List
 \labelwidthstring 00.00.0000
 
 \SpecialChar ~
  When deep_reload is off, IPython will use the normal 
 \family typewriter 
 reload()
 \family default 
 , but deep_reload will still be available as 
 \family typewriter 
 dreload()
 \family default 
 .
  This feature is off by default [which means that you have both normal 
 \family typewriter 
 reload()
 \family default 
  and 
 \family typewriter 
 dreload()
 \family default 
 ].
 \layout List
 \labelwidthstring 00.00.0000
 
 
 \family typewriter 
 \series bold 
 -editor\SpecialChar ~
 <name>
 \family default 
 \series default 
 : Which editor to use with the 
 \family typewriter 
 %edit
 \family default 
  command.
  By default, IPython will honor your 
 \family typewriter 
 EDITOR
 \family default 
  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 
 \family typewriter 
 EDITOR
 \family default 
  is something like Emacs).
 \layout List
 \labelwidthstring 00.00.0000
 
 
 \family typewriter 
 \series bold 
 -ipythondir\SpecialChar ~
 <name>
 \series default 
 :
 \family default 
  name of your IPython configuration directory 
 \family typewriter 
 IPYTHONDIR
 \family default 
 .
  This can also be specified through the environment variable 
 \family typewriter 
 IPYTHONDIR
 \family default 
 .
 \layout List
 \labelwidthstring 00.00.0000
 
 
 \family typewriter 
 \series bold 
 -log|l
 \family default 
 \series default 
 : generate a log file of all input.
  The file is named 
 \family typewriter 
 ipython_log.py
 \family default 
  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 
 \family typewriter 
 -logplay
 \family default 
  (see below).
 \layout List
 \labelwidthstring 00.00.0000
 
 
 \family typewriter 
 \series bold 
 -logfile|lf\SpecialChar ~
 <name>
 \series default 
 : 
 \family default 
 specify the name of your logfile.
 \layout List
 \labelwidthstring 00.00.0000
 
 
 \family typewriter 
 \series bold 
 -logplay|lp\SpecialChar ~
 <name>
 \series default 
 :
 \family default 
  you can 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 
 \family typewriter 
 -logplay
 \family default 
 , IPython will try to reconstruct the previous working environment in full,
  not just execute the commands in the logfile.
 \layout List
 \labelwidthstring 00.00.0000
 
 \SpecialChar ~
  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.
 \layout List
 \labelwidthstring 00.00.0000
 
 \SpecialChar ~
  Caveats: there are limitations in this option.
  The history variables 
 \family typewriter 
 _i*
 \family default 
 ,
 \family typewriter 
 _*
 \family default 
  and 
 \family typewriter 
 _dh
 \family default 
  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.
 \layout List
 \labelwidthstring 00.00.0000
 
 
 \family typewriter 
 \series bold 
 -[no]messages
 \series default 
 :
 \family default 
  Print messages which IPython collects about its startup process (default
  on).
 \layout List
 \labelwidthstring 00.00.0000
 
 
 \family typewriter 
 \series bold 
 -[no]pdb
 \family default 
 \series default 
 : 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.
 \layout List
 \labelwidthstring 00.00.0000
 
 
 \family typewriter 
 \series bold 
 -[no]pprint
 \series default 
 :
 \family default 
  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).
 \layout List
 \labelwidthstring 00.00.0000
 
 
 \family typewriter 
 \series bold 
 -profile|p <name>
 \series default 
 :
 \family default 
  assume that your config file is 
 \family typewriter 
 ipythonrc-<name>
 \family default 
  (looks in current dir first, then in 
 \family typewriter 
 IPYTHONDIR
 \family default 
 ).
  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 
 \family typewriter 
 IPYTHONDIR/ipythonrc
 \family default 
  file and then have other 'profiles' which include this one and load extra
  things for particular tasks.
  For example:
 \layout List
 \labelwidthstring 00.00.0000
 
 
 \family typewriter 
 \SpecialChar ~
  
 \family default 
 1.
 
 \family typewriter 
  $HOME/.ipython/ipythonrc
 \family default 
  : load basic things you always want.
 \layout List
 \labelwidthstring 00.00.0000
 
 
 \family typewriter 
 \SpecialChar ~
  
 \family default 
 2.
 
 \family typewriter 
  $HOME/.ipython/ipythonrc-math
 \family default 
  : load (1) and basic math-related modules.
  
 \layout List
 \labelwidthstring 00.00.0000
 
 
 \family typewriter 
 \SpecialChar ~
  
 \family default 
 3.
 
 \family typewriter 
  $HOME/.ipython/ipythonrc-numeric
 \family default 
  : load (1) and Numeric and plotting modules.
 \layout List
 \labelwidthstring 00.00.0000
 
 \SpecialChar ~
  Since it is possible to create an endless loop by having circular file
  inclusions, IPython will stop if it reaches 15 recursive inclusions.
 \layout List
 \labelwidthstring 00.00.0000
 
 
 \family typewriter 
 \series bold 
 -prompt_in1|pi1\SpecialChar ~
 <string>:
 \family default 
 \series default 
  Specify the string used for input prompts.
  Note that if you are using numbered prompts, the number is represented
  with a '
 \backslash 
 #' in the string.
  Don't forget to quote strings with spaces embedded in them.
  Default: '
 \family typewriter 
 In\SpecialChar ~
 [
 \backslash 
 #]:
 \family default 
 '.
  Sec.\SpecialChar ~
 
 \begin_inset LatexCommand \ref{sec:prompts}
 
 \end_inset 
 
  discusses in detail all the available escapes to customize your prompts.
 \layout List
 \labelwidthstring 00.00.0000
 
 
 \family typewriter 
 \series bold 
 -prompt_in2|pi2\SpecialChar ~
 <string>:
 \family default 
 \series default 
  Similar to the previous option, but used for the continuation prompts.
  The special sequence '
 \family typewriter 
 
 \backslash 
 D
 \family default 
 ' is similar to '
 \family typewriter 
 
 \backslash 
 #
 \family default 
 ', but with all digits replaced dots (so you can have your continuation
  prompt aligned with your input prompt).
  Default: '
 \family typewriter 
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 .
 \backslash 
 D.:
 \family default 
 ' (note three spaces at the start for alignment with '
 \family typewriter 
 In\SpecialChar ~
 [
 \backslash 
 #]
 \family default 
 ').
 \layout List
 \labelwidthstring 00.00.0000
 
 
 \family typewriter 
 \series bold 
 -prompt_out|po\SpecialChar ~
 <string>:
 \family default 
 \series default 
  String used for output prompts, also uses numbers like 
 \family typewriter 
 prompt_in1
 \family default 
 .
  Default: '
 \family typewriter 
 Out[
 \backslash 
 #]:
 \family default 
 '
 \layout List
 \labelwidthstring 00.00.0000
 
 
 \family typewriter 
 \series bold 
 -quick
 \family default 
 \series default 
 : start in bare bones mode (no config file loaded).
 \layout List
 \labelwidthstring 00.00.0000
 
 
 \family typewriter 
 \series bold 
 -rcfile\SpecialChar ~
 <name>
 \series default 
 :
 \family default 
  name of your IPython resource configuration file.
  Normally IPython loads ipythonrc (from current directory) or
 \family typewriter 
  IPYTHONDIR/ipythonrc
 \family default 
 .
 \layout List
 \labelwidthstring 00.00.0000
 
 \SpecialChar ~
  If the loading of your config file fails, IPython starts with a bare bones
  configuration (no modules loaded at all).
 \layout List
 \labelwidthstring 00.00.0000
 
 
 \family typewriter 
 \series bold 
 -[no]readline
 \family default 
 \series default 
 : 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.
 \layout List
 \labelwidthstring 00.00.0000
 
 \SpecialChar ~
  Note that X/Emacs 'eterm' buffers (opened with 
 \family typewriter 
 M-x\SpecialChar ~
 term
 \family default 
 ) support IPython's readline and syntax coloring fine, only 'emacs' (
 \family typewriter 
 M-x\SpecialChar ~
 shell
 \family default 
  and 
 \family typewriter 
 C-c\SpecialChar ~
 !
 \family default 
 ) buffers do not.
 \layout List
 \labelwidthstring 00.00.0000
 
 
 \family typewriter 
 \series bold 
 -screen_length|sl\SpecialChar ~
 <n>
 \series default 
 :
 \family default 
  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.
 \layout List
 \labelwidthstring 00.00.0000
 
 \SpecialChar ~
  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.
 \layout List
 \labelwidthstring 00.00.0000
 
 
 \family typewriter 
 \series bold 
 -separate_in|si\SpecialChar ~
 <string>
 \series default 
 :
 \family default 
  separator before input prompts.
  Default: '
 \family typewriter 
 
 \backslash 
 n
 \family default 
 '
 \layout List
 \labelwidthstring 00.00.0000
 
 
 \family typewriter 
 \series bold 
 -separate_out|so\SpecialChar ~
 <string>
 \family default 
 \series default 
 : separator before output prompts.
  Default: nothing.
 \layout List
 \labelwidthstring 00.00.0000
 
 
 \family typewriter 
 \series bold 
 -separate_out2|so2\SpecialChar ~
 <string>
 \series default 
 :
 \family default 
  separator after output prompts.
  Default: nothing.
 \layout List
 \labelwidthstring 00.00.0000
 
 \SpecialChar ~
  For these three options, use the value 0 to specify no separator.
 \layout List
 \labelwidthstring 00.00.0000
 
 
 \family typewriter 
 \series bold 
 -nosep
 \series default 
 : 
 \family default 
 shorthand for 
 \family typewriter 
 '-SeparateIn 0 -SeparateOut 0 -SeparateOut2 0'
 \family default 
 .
  Simply removes all input/output separators.
 \layout List
 \labelwidthstring 00.00.0000
 
 
 \family typewriter 
 \series bold 
 -upgrade
 \family default 
 \series default 
 : allows you to upgrade your 
 \family typewriter 
 IPYTHONDIR
 \family default 
  configuration when you install a new version of IPython.
  Since new versions may include new command line options or example files,
  this copies updated ipythonrc-type files.
  However, it backs up (with a 
 \family typewriter 
 .old
 \family default 
  extension) all files which it overwrites so that you can merge back any
  customizations you might have in your personal files.
 \layout List
 \labelwidthstring 00.00.0000
 
 
 \family typewriter 
 \series bold 
 -Version
 \series default 
 :
 \family default 
  print version information and exit.
 \layout List
 \labelwidthstring 00.00.0000
 
 
 \family typewriter 
 \series bold 
 -wxversion\SpecialChar ~
 <string>:
 \family default 
 \series default 
  Select a specific version of wxPython (used in conjunction with 
 \family typewriter 
 -wthread
 \family default 
 ).
  Requires the wxversion module, part of recent wxPython distributions
 \layout List
 \labelwidthstring 00.00.0000
 
 
 \family typewriter 
 \series bold 
 -xmode\SpecialChar ~
 <modename>
 \series default 
 :
 \family default 
  Mode for exception reporting.
 \layout List
 \labelwidthstring 00.00.0000
 
 \SpecialChar ~
  Valid modes: Plain, Context and Verbose.
 \layout List
 \labelwidthstring 00.00.0000
 
 \SpecialChar ~
  Plain: similar to python's normal traceback printing.
 \layout List
 \labelwidthstring 00.00.0000
 
 \SpecialChar ~
  Context: prints 5 lines of context source code around each line in the
  traceback.
 \layout List
 \labelwidthstring 00.00.0000
 
 \SpecialChar ~
  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).
 \layout Section
 
 Interactive use
 \layout Standard
 
 
 \series bold 
 Warning
 \series default 
 : IPython relies on the existence of a global variable called 
 \family typewriter 
 __IP
 \family default 
  which controls the shell itself.
  If you redefine 
 \family typewriter 
 __IP
 \family default 
  to anything, bizarre behavior will quickly occur.
 \layout Standard
 
 Other than the above warning, IPython is meant to work as a drop-in replacement
  for the standard interactive interpreter.
  As such, any code which is valid python should execute normally under IPython
  (cases where this is not true should be reported as bugs).
  It does, however, offer many features which are not available at a standard
  python prompt.
  What follows is a list of these.
 \layout Subsection
 
 Caution for Windows users
 \layout Standard
 
 Windows, unfortunately, uses the `
 \family typewriter 
 
 \backslash 
 
 \family default 
 ' character as a path separator.
  This is a terrible choice, because `
 \family typewriter 
 
 \backslash 
 
 \family default 
 ' also represents the escape character in most modern programming languages,
  including Python.
  For this reason, issuing many of the commands discussed below (especially
  magics which affect the filesystem) with `
 \family typewriter 
 
 \backslash 
 
 \family default 
 ' in them will cause strange errors.
 \layout Standard
 
 A partial solution is to use instead the `
 \family typewriter 
 /
 \family default 
 ' character as a path separator, which Windows recognizes in 
 \emph on 
 most
 \emph default 
  situations.
  However, in Windows commands `
 \family typewriter 
 /
 \family default 
 ' flags options, so you can not use it for the root directory.
  This means that paths beginning at the root must be typed in a contrived
  manner like:
 \newline 
 
 \family typewriter 
 %copy 
 \backslash 
 opt/foo/bar.txt 
 \backslash 
 tmp
 \layout Standard
 
 There is no sensible thing IPython can do to truly work around this flaw
  in Windows
 \begin_inset Foot
 collapsed true
 
 \layout Standard
 
 If anyone comes up with a 
 \emph on 
 clean
 \emph default 
  solution which works consistently and does not negatively impact other
  platforms at all, I'll gladly accept a patch.
 \end_inset 
 
 .
 \layout Subsection
 
 
 \begin_inset LatexCommand \label{sec:magic}
 
 \end_inset 
 
 Magic command system
 \layout Standard
 
 IPython will treat any line whose first character is a 
 \family typewriter 
 %
 \family default 
  as a special call to a 'magic' function.
  These allow you to control the behavior of IPython itself, plus a lot of
  system-type features.
  They are all prefixed with a 
 \family typewriter 
 %
 \family default 
  character, but parameters are given without parentheses or quotes.
 \layout Standard
 
 Example: typing 
 \family typewriter 
 '%cd mydir'
 \family default 
  (without the quotes) changes you working directory to 
 \family typewriter 
 'mydir'
 \family default 
 , if it exists.
 \layout Standard
 
 If you have 'automagic' enabled (in your 
 \family typewriter 
 ipythonrc
 \family default 
  file, via the command line option 
 \family typewriter 
 -automagic 
 \family default 
 or with the 
 \family typewriter 
 %automagic
 \family default 
  function), you don't need to type in the 
 \family typewriter 
 %
 \family default 
  explicitly.
  IPython will scan its internal list of magic functions and call one if
  it exists.
  With automagic on you can then just type '
 \family typewriter 
 cd mydir
 \family default 
 ' to go to directory '
 \family typewriter 
 mydir
 \family default 
 '.
  The automagic system has the lowest possible precedence in name searches,
  so defining an identifier with the same name as an existing magic function
  will shadow it for automagic use.
  You can still access the shadowed magic function by explicitly using the
  
 \family typewriter 
 %
 \family default 
  character at the beginning of the line.
 \layout Standard
 
 An example (with automagic on) should clarify all this:
 \layout LyX-Code
 
 In [1]: cd ipython # %cd is called by automagic
 \layout LyX-Code
 
 /home/fperez/ipython
 \layout LyX-Code
 
 In [2]: cd=1 # now cd is just a variable
 \layout LyX-Code
 
 In [3]: cd ..
  # and doesn't work as a function anymore
 \layout LyX-Code
 
 ------------------------------------------------------------
 \layout LyX-Code
 
     File "<console>", line 1
 \layout LyX-Code
 
       cd ..
 \layout LyX-Code
 
           ^
 \layout LyX-Code
 
 SyntaxError: invalid syntax
 \layout LyX-Code
 
 \layout LyX-Code
 
 In [4]: %cd ..
  # but %cd always works
 \layout LyX-Code
 
 /home/fperez
 \layout LyX-Code
 
 In [5]: del cd # if you remove the cd variable
 \layout LyX-Code
 
 In [6]: cd ipython # automagic can work again
 \layout LyX-Code
 
 /home/fperez/ipython
 \layout Standard
 
 You can define your own magic functions to extend the system.
  The following is a snippet of code which shows how to do it.
  It is provided as file 
 \family typewriter 
 example-magic.py
 \family default 
  in the examples directory:
 \layout Standard
 
 
 \begin_inset ERT
 status Open
 
 \layout Standard
 
 \backslash 
 codelist{examples/example-magic.py}
 \end_inset 
 
 
 \layout Standard
 
 You can also define your own aliased names for magic functions.
  In your 
 \family typewriter 
 ipythonrc
 \family default 
  file, placing a line like:
 \layout Standard
 
 
 \family typewriter 
 execute __IP.magic_cl = __IP.magic_clear
 \layout Standard
 
 will define 
 \family typewriter 
 %cl
 \family default 
  as a new name for 
 \family typewriter 
 %clear
 \family default 
 .
 \layout Standard
 
 Type 
 \family typewriter 
 %magic
 \family default 
  for more information, including a list of all available magic functions
  at any time and their docstrings.
  You can also type 
 \family typewriter 
 %magic_function_name?
 \family default 
  (see sec.
  
 \begin_inset LatexCommand \ref{sec:dyn-object-info}
 
 \end_inset 
 
  for information on the 
 \family typewriter 
 '?'
 \family default 
  system) to get information about any particular magic function you are
  interested in.
 \layout Subsubsection
 
 Magic commands
 \layout Standard
 
 The rest of this section is automatically generated for each release from
  the docstrings in the IPython code.
  Therefore the formatting is somewhat minimal, but this method has the advantage
  of having information always in sync with the code.
 \layout Standard
 
 A list of all the magic commands available in IPython's 
 \emph on 
 default
 \emph default 
  installation follows.
  This is similar to what you'll see by simply typing 
 \family typewriter 
 %magic
 \family default 
  at the prompt, but that will also give you information about magic commands
  you may have added as part of your personal customizations.
 \layout Standard
 
 
 \begin_inset Include \input{magic.tex}
 preview false
 
 \end_inset 
 
 
 \layout Subsection
 
 Access to the standard Python help
 \layout Standard
 
 As of Python 2.1, a help system is available with access to object docstrings
  and the Python manuals.
  Simply type 
 \family typewriter 
 'help'
 \family default 
  (no quotes) to access it.
  You can also type 
 \family typewriter 
 help(object)
 \family default 
  to obtain information about a given object, and 
 \family typewriter 
 help('keyword')
 \family default 
  for information on a keyword.
  As noted in sec.
  
 \begin_inset LatexCommand \ref{sec:help-access}
 
 \end_inset 
 
 , you need to properly configure your environment variable 
 \family typewriter 
 PYTHONDOCS
 \family default 
  for this feature to work correctly.
 \layout Subsection
 
 
 \begin_inset LatexCommand \label{sec:dyn-object-info}
 
 \end_inset 
 
 Dynamic object information
 \layout Standard
 
 Typing 
 \family typewriter 
 ?word
 \family default 
  or 
 \family typewriter 
 word?
 \family default 
  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.
  This system gives access variable types and values, full source code for
  any object (if available), function prototypes and other useful information.
 \layout Standard
 
 Typing 
 \family typewriter 
 ??word
 \family default 
  or 
 \family typewriter 
 word??
 \family default 
  gives access to the full information without snipping long strings.
  Long strings are sent to the screen through the 
 \family typewriter 
 less
 \family default 
  pager if longer than the screen and printed otherwise.
  On systems lacking the 
 \family typewriter 
 less
 \family default 
  command, IPython uses a very basic internal pager.
 \layout Standard
 
 The following magic functions are particularly useful for gathering information
  about your working environment.
  You can get more details by typing 
 \family typewriter 
 %magic
 \family default 
  or querying them individually (use 
 \family typewriter 
 %function_name?
 \family default 
  with or without the 
 \family typewriter 
 %
 \family default 
 ), this is just a summary:
 \layout List
 \labelwidthstring 00.00.0000
 
 
 \family typewriter 
 \series bold 
 %pdoc\SpecialChar ~
 <object>
 \family default 
 \series default 
 : Print (or run through a pager if too long) the docstring for an object.
  If the given object is a class, it will print both the class and the constructo
 r docstrings.
 \layout List
 \labelwidthstring 00.00.0000
 
 
 \family typewriter 
 \series bold 
 %pdef\SpecialChar ~
 <object>
 \family default 
 \series default 
 : Print the definition header for any callable object.
  If the object is a class, print the constructor information.
 \layout List
 \labelwidthstring 00.00.0000
 
 
 \family typewriter 
 \series bold 
 %psource\SpecialChar ~
 <object>
 \family default 
 \series default 
 : Print (or run through a pager if too long) the source code for an object.
 \layout List
 \labelwidthstring 00.00.0000
 
 
 \family typewriter 
 \series bold 
 %pfile\SpecialChar ~
 <object>
 \family default 
 \series default 
 : Show the entire source file where an object was defined via a pager, opening
  it at the line where the object definition begins.
 \layout List
 \labelwidthstring 00.00.0000
 
 
 \family typewriter 
 \series bold 
 %who/%whos
 \family default 
 \series default 
 : These functions give information about identifiers you have defined interactiv
 ely (not things you loaded or defined in your configuration files).
  
 \family typewriter 
 %who
 \family default 
  just prints a list of identifiers and 
 \family typewriter 
 %whos
 \family default 
  prints a table with some basic details about each identifier.
 \layout Standard
 
 Note that the dynamic object information functions (
 \family typewriter 
 ?/??, %pdoc, %pfile, %pdef, %psource
 \family default 
 ) give you access to documentation even on things which are not really defined
  as separate identifiers.
  Try for example typing 
 \family typewriter 
 {}.get?
 \family default 
  or after doing 
 \family typewriter 
 import os
 \family default 
 , type 
 \family typewriter 
 os.path.abspath??
 \family default 
 .
 \layout Subsection
 
 
 \begin_inset LatexCommand \label{sec:readline}
 
 \end_inset 
 
 Readline-based features
 \layout Standard
 
 These features require the GNU readline library, so they won't work if your
  Python installation lacks readline support.
  We will first describe the default behavior IPython uses, and then how
  to change it to suit your preferences.
 \layout Subsubsection
 
 Command line completion
 \layout Standard
 
 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 if no python names
  match what you've typed so far.
 \layout Subsubsection
 
 Search command history
 \layout Standard
 
 IPython provides two ways for searching through previous input and thus
  reduce the need for repetitive typing:
 \layout Enumerate
 
 Start typing, and then use 
 \family typewriter 
 Ctrl-p
 \family default 
  (previous,up) and 
 \family typewriter 
 Ctrl-n
 \family default 
  (next,down) to search through only the history items that match what you've
  typed so far.
  If you use 
 \family typewriter 
 Ctrl-p/Ctrl-n
 \family default 
  at a blank prompt, they just behave like normal arrow keys.
 \layout Enumerate
 
 Hit 
 \family typewriter 
 Ctrl-r
 \family default 
 : opens a search prompt.
  Begin typing and the system searches your history for lines that contain
  what you've typed so far, completing as much as it can.
 \layout Subsubsection
 
 Persistent command history across sessions
 \layout Standard
 
 IPython will save your input history when it leaves and reload it next time
  you restart it.
  By default, the history file is named 
 \family typewriter 
 $IPYTHONDIR/history
 \family default 
 , but if you've loaded a named profile, '
 \family typewriter 
 -PROFILE_NAME
 \family default 
 ' is appended to the name.
  This allows you to keep separate histories related to various tasks: commands
  related to numerical work will not be clobbered by a system shell history,
  for example.
 \layout Subsubsection
 
 Autoindent
 \layout Standard
 
 IPython can recognize lines ending in ':' and indent the next line, while
  also un-indenting automatically after 'raise' or 'return'.
  
 \layout Standard
 
 This feature uses the readline library, so it will honor your 
 \family typewriter 
 ~/.inputrc
 \family default 
  configuration (or whatever file your 
 \family typewriter 
 INPUTRC
 \family default 
  variable points to).
  Adding the following lines to your 
 \family typewriter 
 .inputrc
 \family default 
  file can make indenting/unindenting more convenient (
 \family typewriter 
 M-i
 \family default 
  indents, 
 \family typewriter 
 M-u
 \family default 
  unindents):
 \layout Standard
 
 
 \family typewriter 
 $if Python
 \newline 
 "
 \backslash 
 M-i": "\SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 " 
 \newline 
 "
 \backslash 
 M-u": "
 \backslash 
 d
 \backslash 
 d
 \backslash 
 d
 \backslash 
 d" 
 \newline 
 $endif
 \layout Standard
 
 Note that there are 4 spaces between the quote marks after 
 \family typewriter 
 "M-i"
 \family default 
  above.
 \layout Standard
 
 
 \series bold 
 Warning:
 \series default 
  this feature is ON by default, but it can cause problems with the pasting
  of multi-line indented code (the pasted code gets re-indented on each line).
  A magic function 
 \family typewriter 
 %autoindent
 \family default 
  allows you to toggle it on/off at runtime.
  You can also disable it permanently on in your 
 \family typewriter 
 ipythonrc
 \family default 
  file (set 
 \family typewriter 
 autoindent 0
 \family default 
 ).
 \layout Subsubsection
 
 Customizing readline behavior
 \layout Standard
 
 All these features are based on the GNU readline library, which has an extremely
  customizable interface.
  Normally, readline is configured via a file which defines the behavior
  of the library; the details of the syntax for this can be found in the
  readline documentation available with your system or on the Internet.
  IPython doesn't read this file (if it exists) directly, but it does support
  passing to readline valid options via a simple interface.
  In brief, you can customize readline by setting the following options in
  your 
 \family typewriter 
 ipythonrc
 \family default 
  configuration file (note that these options can 
 \emph on 
 not
 \emph default 
  be specified at the command line):
 \layout List
 \labelwidthstring 00.00.0000
 
 
 \family typewriter 
 \series bold 
 readline_parse_and_bind:
 \family default 
 \series default 
  this option can appear as many times as you want, each time defining a
  string to be executed via a 
 \family typewriter 
 readline.parse_and_bind()
 \family default 
  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.
 \layout List
 \labelwidthstring 00.00.0000
 
 
 \family typewriter 
 \series bold 
 readline_remove_delims:
 \family default 
 \series default 
  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.
  Do not change the default value unless you know what you're doing.
 \layout List
 \labelwidthstring 00.00.0000
 
 
 \family typewriter 
 \series bold 
 readline_omit__names
 \family default 
 \series default 
 : when tab-completion is enabled, hitting 
 \family typewriter 
 <tab>
 \family default 
  after a '
 \family typewriter 
 .
 \family default 
 ' in a name will complete all attributes of an object, including all the
  special methods whose names include double underscores (like 
 \family typewriter 
 __getitem__
 \family default 
  or 
 \family typewriter 
 __class__
 \family default 
 ).
  If you'd rather not see these names by default, you can set this option
  to 1.
  Note that even when this option is set, you can still see those names by
  explicitly typing a 
 \family typewriter 
 _
 \family default 
  after the period and hitting 
 \family typewriter 
 <tab>
 \family default 
 : '
 \family typewriter 
 name._<tab>
 \family default 
 ' will always complete attribute names starting with '
 \family typewriter 
 _
 \family default 
 '.
 \layout List
 \labelwidthstring 00.00.0000
 
 \SpecialChar ~
  This option is off by default so that new users see all attributes of any
  objects they are dealing with.
 \layout Standard
 
 You will find the default values along with a corresponding detailed explanation
  in your 
 \family typewriter 
 ipythonrc
 \family default 
  file.
 \layout Subsection
 
 Session logging and restoring
 \layout Standard
 
 You can log all input from a session either by starting IPython with the
  command line switches 
 \family typewriter 
 -log
 \family default 
  or 
 \family typewriter 
 -logfile 
 \family default 
 (see sec.
  
 \begin_inset LatexCommand \ref{sec:cmd-line-opts}
 
 \end_inset 
 
 )or by activating the logging at any moment with the magic function 
 \family typewriter 
 %logstart
 \family default 
 .
  
 \layout Standard
 
 Log files can later be reloaded with the 
 \family typewriter 
 -logplay
 \family default 
  option and IPython will attempt to 'replay' the log by executing all the
  lines in it, thus restoring the state of a previous session.
  This feature is not quite perfect, but can still be useful in many cases.
 \layout Standard
 
 The log files can also be used as a way to have a permanent record of any
  code you wrote while experimenting.
  Log files are regular text files which you can later open in your favorite
  text editor to extract code or to 'clean them up' before using them to
  replay a session.
 \layout Standard
 
 The 
 \family typewriter 
 %logstart
 \family default 
  function for activating logging in mid-session is used as follows:
 \layout Standard
 
 
 \family typewriter 
 %logstart [log_name [log_mode]]
 \layout Standard
 
 If no name is given, it defaults to a file named 
 \family typewriter 
 'log'
 \family default 
  in your IPYTHONDIR directory, in 
 \family typewriter 
 'rotate'
 \family default 
  mode (see below).
 \layout Standard
 
 '
 \family typewriter 
 %logstart name
 \family default 
 ' saves to file 
 \family typewriter 
 'name'
 \family default 
  in 
 \family typewriter 
 'backup'
 \family default 
  mode.
  It saves your history up to that point and then continues logging.
 \layout Standard
 
 
 \family typewriter 
 %logstart
 \family default 
  takes a second optional parameter: logging mode.
  This can be one of (note that the modes are given unquoted):
 \layout List
 \labelwidthstring 00.00.0000
 
 
 \family typewriter 
 over
 \family default 
 : overwrite existing 
 \family typewriter 
 log_name
 \family default 
 .
 \layout List
 \labelwidthstring 00.00.0000
 
 
 \family typewriter 
 backup
 \family default 
 : rename (if exists) to 
 \family typewriter 
 log_name~
 \family default 
  and start 
 \family typewriter 
 log_name
 \family default 
 .
 \layout List
 \labelwidthstring 00.00.0000
 
 
 \family typewriter 
 append
 \family default 
 : well, that says it.
 \layout List
 \labelwidthstring 00.00.0000
 
 
 \family typewriter 
 rotate
 \family default 
 : create rotating logs 
 \family typewriter 
 log_name
 \family default 
 .
 \family typewriter 
 1~
 \family default 
 , 
 \family typewriter 
 log_name.2~
 \family default 
 , etc.
 \layout Standard
 
 The 
 \family typewriter 
 %logoff
 \family default 
  and 
 \family typewriter 
 %logon
 \family default 
  functions allow you to temporarily stop and resume logging to a file which
  had previously been started with 
 \family typewriter 
 %logstart
 \family default 
 .
  They will fail (with an explanation) if you try to use them before logging
  has been started.
 \layout Subsection
 
 
 \begin_inset LatexCommand \label{sub:System-shell-access}
 
 \end_inset 
 
 System shell access
 \layout Standard
 
 Any input line beginning with a 
 \family typewriter 
 !
 \family default 
  character is passed verbatim (minus the 
 \family typewriter 
 !
 \family default 
 , of course) to the underlying operating system.
  For example, typing 
 \family typewriter 
 !ls
 \family default 
  will run 
 \family typewriter 
 'ls'
 \family default 
  in the current directory.
 \layout Subsubsection
 
 Manual capture of command output
 \layout Standard
 
 If the input line begins with 
 \emph on 
 two
 \emph default 
  exclamation marks, 
 \family typewriter 
 !!
 \family default 
 , the command is executed but its output is captured and returned as a python
  list, split on newlines.
  Any output sent by the subprocess to standard error is printed separately,
  so that the resulting list only captures standard output.
  The 
 \family typewriter 
 !!
 \family default 
  syntax is a shorthand for the 
 \family typewriter 
 %sx
 \family default 
  magic command.
 \layout Standard
 
 Finally, the 
 \family typewriter 
 %sc
 \family default 
  magic (short for `shell capture') is similar to 
 \family typewriter 
 %sx
 \family default 
 , but allowing more fine-grained control of the capture details, and storing
  the result directly into a named variable.
 \layout Standard
 
 See Sec.\SpecialChar ~
 
 \begin_inset LatexCommand \ref{sec:magic}
 
 \end_inset 
 
  for details on the magics 
 \family typewriter 
 %sc
 \family default 
  and 
 \family typewriter 
 %sx
 \family default 
 , or use IPython's own help (
 \family typewriter 
 sc?
 \family default 
  and 
 \family typewriter 
 sx?
 \family default 
 ) for further details.
 \layout Standard
 
 IPython also allows you to expand the value of python variables when making
  system calls.
  Any python variable or expression which you prepend with 
 \family typewriter 
 $
 \family default 
  will get expanded before the system call is made.
  
 \layout Standard
 
 
 \family typewriter 
 In [1]: pyvar='Hello world'
 \newline 
 In [2]: !echo "A python variable: $pyvar" 
 \newline 
 A python variable: Hello world
 \layout Standard
 
 If you want the shell to actually see a literal 
 \family typewriter 
 $
 \family default 
 , you need to type it twice:
 \layout Standard
 
 
 \family typewriter 
 In [3]: !echo "A system variable: $$HOME" 
 \newline 
 A system variable: /home/fperez
 \layout Standard
 
 You can pass arbitrary expressions, though you'll need to delimit them with
  
 \family typewriter 
 {}
 \family default 
  if there is ambiguity as to the extent of the expression:
 \layout Standard
 
 
 \family typewriter 
 In [5]: x=10
 \newline 
 In [6]: y=20
 \newline 
 In [13]: !echo $x+y 
 \newline 
 10+y 
 \newline 
 In [7]: !echo ${x+y} 
 \newline 
 30 
 \layout Standard
 
 Even object attributes can be expanded:
 \layout Standard
 
 
 \family typewriter 
 In [12]: !echo $sys.argv 
 \newline 
 [/home/fperez/usr/bin/ipython] 
 \layout Subsection
 
 System command aliases
 \layout Standard
 
 The 
 \family typewriter 
 %alias
 \family default 
  magic function and the 
 \family typewriter 
 alias
 \family default 
  option in the 
 \family typewriter 
 ipythonrc
 \family default 
  configuration file allow you to define magic functions which are in fact
  system shell commands.
  These aliases can have parameters.
  
 \layout Standard
 
 '
 \family typewriter 
 %alias alias_name cmd
 \family default 
 ' defines '
 \family typewriter 
 alias_name
 \family default 
 ' as an alias for '
 \family typewriter 
 cmd
 \family default 
 ' 
 \layout Standard
 
 Then, typing '
 \family typewriter 
 %alias_name params
 \family default 
 ' will execute the system command '
 \family typewriter 
 cmd params
 \family default 
 ' (from your underlying operating system).
  
 \layout Standard
 
 You can also define aliases with parameters using 
 \family typewriter 
 %s
 \family default 
  specifiers (one per parameter).
  The following example defines the 
 \family typewriter 
 %parts
 \family default 
  function as an alias to the command '
 \family typewriter 
 echo first %s second %s
 \family default 
 ' where each 
 \family typewriter 
 %s
 \family default 
  will be replaced by a positional parameter to the call to 
 \family typewriter 
 %parts:
 \layout Standard
 
 
 \family typewriter 
 In [1]: alias parts echo first %s second %s
 \newline 
 In [2]: %parts A B
 \newline 
 first A second B 
 \newline 
 In [3]: %parts A 
 \newline 
 Incorrect number of arguments: 2 expected.
  
 \newline 
 parts is an alias to: 'echo first %s second %s' 
 \layout Standard
 
 If called with no parameters, 
 \family typewriter 
 %alias
 \family default 
  prints the table of currently defined aliases.
 \layout Standard
 
 The 
 \family typewriter 
 %rehash/rehashx
 \family default 
  magics allow you to load your entire 
 \family typewriter 
 $PATH
 \family default 
  as ipython aliases.
  See their respective docstrings (or sec.\SpecialChar ~
 
 \begin_inset LatexCommand \ref{sec:magic}
 
 \end_inset 
 
  for further details).
 \layout Subsection
 
 
 \begin_inset LatexCommand \label{sec:dreload}
 
 \end_inset 
 
 Recursive reload
 \layout Standard
 
 The 
 \family typewriter 
 dreload
 \family default 
  function does a recursive reload of a module: changes made to the module
  since you imported will actually be available without having to exit.
 \layout Subsection
 
 Verbose and colored exception traceback printouts
 \layout Standard
 
 IPython provides the option to see very detailed exception tracebacks, which
  can be especially useful when debugging large programs.
  You can run any Python file with the 
 \family typewriter 
 %run
 \family default 
  function to benefit from these detailed tracebacks.
  Furthermore, both normal and verbose tracebacks can be colored (if your
  terminal supports it) which makes them much easier to parse visually.
 \layout Standard
 
 See the magic 
 \family typewriter 
 xmode
 \family default 
  and 
 \family typewriter 
 colors
 \family default 
  functions for details (just type 
 \family typewriter 
 %magic
 \family default 
 ).
 \layout Standard
 
 These features are basically a terminal version of Ka-Ping Yee's 
 \family typewriter 
 cgitb
 \family default 
  module, now part of the standard Python library.
 \layout Subsection
 
 
 \begin_inset LatexCommand \label{sec:cache_input}
 
 \end_inset 
 
 Input caching system
 \layout Standard
 
 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).
 \layout Standard
 
 The following GLOBAL variables always exist (so don't overwrite them!):
  
 \family typewriter 
 _i
 \family default 
 : stores previous input.
  
 \family typewriter 
 _ii
 \family default 
 : next previous.
  
 \family typewriter 
 _iii
 \family default 
 : next-next previous.
  
 \family typewriter 
 _ih
 \family default 
  : a list of all input 
 \family typewriter 
 _ih[n]
 \family default 
  is the input from line 
 \family typewriter 
 n
 \family default 
  and this list is aliased to the global variable 
 \family typewriter 
 In
 \family default 
 .
  If you overwrite 
 \family typewriter 
 In
 \family default 
  with a variable of your own, you can remake the assignment to the internal
  list with a simple 
 \family typewriter 
 'In=_ih'
 \family default 
 .
 \layout Standard
 
 Additionally, global variables named 
 \family typewriter 
 _i<n>
 \family default 
  are dynamically created (
 \family typewriter 
 <n>
 \family default 
  being the prompt counter), such that 
 \newline 
 
 \family typewriter 
 _i<n> == _ih[<n>] == In[<n>].
 \layout Standard
 
 For example, what you typed at prompt 14 is available as 
 \family typewriter 
 _i14,
 \family default 
  
 \family typewriter 
 _ih[14]
 \family default 
  and 
 \family typewriter 
 In[14]
 \family default 
 .
 \layout Standard
 
 This allows you to easily cut and paste multi line interactive prompts by
  printing them out: they print like a clean string, without prompt characters.
  You can also manipulate them like regular variables (they are strings),
  modify or exec them (typing 
 \family typewriter 
 'exec _i9'
 \family default 
  will re-execute the contents of input prompt 9, '
 \family typewriter 
 exec In[9:14]+In[18]
 \family default 
 ' will re-execute lines 9 through 13 and line 18).
 \layout Standard
 
 You can also re-execute multiple lines of input easily by using the magic
  
 \family typewriter 
 %macro
 \family default 
  function (which automates the process and allows re-execution without having
  to type '
 \family typewriter 
 exec
 \family default 
 ' every time).
  The macro system also allows you to re-execute previous lines which include
  magic function calls (which require special processing).
  Type 
 \family typewriter 
 %macro?
 \family default 
  or see sec.
  
 \begin_inset LatexCommand \ref{sec:magic}
 
 \end_inset 
 
  for more details on the macro system.
 \layout Standard
 
 A history function 
 \family typewriter 
 %hist
 \family default 
  allows you to see any part of your input history by printing a range of
  the 
 \family typewriter 
 _i
 \family default 
  variables.
 \layout Subsection
 
 
 \begin_inset LatexCommand \label{sec:cache_output}
 
 \end_inset 
 
 Output caching system
 \layout Standard
 
 For output that is returned from actions, a system similar to the input
  cache exists but using 
 \family typewriter 
 _
 \family default 
  instead of 
 \family typewriter 
 _i
 \family default 
 .
  Only actions that produce a result (NOT assignments, for example) are cached.
  If you are familiar with Mathematica, IPython's 
 \family typewriter 
 _
 \family default 
  variables behave exactly like Mathematica's 
 \family typewriter 
 %
 \family default 
  variables.
 \layout Standard
 
 The following GLOBAL variables always exist (so don't overwrite them!):
  
 \layout List
 \labelwidthstring 00.00.0000
 
 
 \family typewriter 
 \series bold 
 _
 \family default 
 \series default 
  (a 
 \emph on 
 single
 \emph default 
  underscore) : stores previous output, like Python's default interpreter.
 \layout List
 \labelwidthstring 00.00.0000
 
 
 \family typewriter 
 \series bold 
 __
 \family default 
 \series default 
  (two underscores): next previous.
 \layout List
 \labelwidthstring 00.00.0000
 
 
 \family typewriter 
 \series bold 
 ___
 \family default 
 \series default 
  (three underscores): next-next previous.
 \layout Standard
 
 Additionally, global variables named 
 \family typewriter 
 _<n> 
 \family default 
 are dynamically created (
 \family typewriter 
 <n>
 \family default 
  being the prompt counter), such that the result of output 
 \family typewriter 
 <n>
 \family default 
  is always available as 
 \family typewriter 
 _<n>
 \family default 
  (don't use the angle brackets, just the number, e.g.
  
 \family typewriter 
 _21
 \family default 
 ).
 \layout Standard
 
 These global variables are all stored in a global dictionary (not a list,
  since it only has entries for lines which returned a result) available
  under the names 
 \family typewriter 
 _oh
 \family default 
  and 
 \family typewriter 
 Out
 \family default 
  (similar to 
 \family typewriter 
 _ih
 \family default 
  and 
 \family typewriter 
 In
 \family default 
 ).
  So the output from line 12 can be obtained as 
 \family typewriter 
 _12
 \family default 
 , 
 \family typewriter 
 Out[12]
 \family default 
  or 
 \family typewriter 
 _oh[12]
 \family default 
 .
  If you accidentally overwrite the 
 \family typewriter 
 Out
 \family default 
  variable you can recover it by typing 
 \family typewriter 
 'Out=_oh
 \family default 
 ' at the prompt.
 \layout Standard
 
 This system obviously can potentially put heavy memory demands on your system,
  since it prevents Python's garbage collector from removing any previously
  computed results.
  You can control how many results are kept in memory with the option (at
  the command line or in your 
 \family typewriter 
 ipythonrc
 \family default 
  file) 
 \family typewriter 
 cache_size
 \family default 
 .
  If you set it to 0, the whole system is completely disabled and the prompts
  revert to the classic 
 \family typewriter 
 '>>>'
 \family default 
  of normal Python.
 \layout Subsection
 
 Directory history
 \layout Standard
 
 Your history of visited directories is kept in the global list 
 \family typewriter 
 _dh
 \family default 
 , and the magic 
 \family typewriter 
 %cd
 \family default 
  command can be used to go to any entry in that list.
  The 
 \family typewriter 
 %dhist
 \family default 
  command allows you to view this history.
 \layout Subsection
 
 Automatic parentheses and quotes
 \layout Standard
 
 These features were adapted from Nathan Gray's LazyPython.
  They are meant to allow less typing for common situations.
 \layout Subsubsection
 
 Automatic parentheses
 \layout Standard
 
 Callable objects (i.e.
  functions, methods, etc) can be invoked like this (notice the commas between
  the arguments):
 \layout Standard
 
 
 \family typewriter 
 >>> callable_ob arg1, arg2, arg3 
 \layout Standard
 
 and the input will be translated to this: 
 \layout Standard
 
 
 \family typewriter 
 --> callable_ob(arg1, arg2, arg3) 
 \layout Standard
 
 You can force automatic parentheses by using '/' as the first character
  of a line.
  For example:
 \layout Standard
 
 
 \family typewriter 
 >>> /globals # becomes 'globals()' 
 \layout Standard
 
 Note that the '/' MUST be the first character on the line! This won't work:
  
 \layout Standard
 
 
 \family typewriter 
 >>> print /globals # syntax error
 \layout Standard
 
 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): 
 \layout Standard
 
 
 \family typewriter 
 In [1]: zip (1,2,3),(4,5,6) # won't work 
 \layout Standard
 
 but this will work: 
 \layout Standard
 
 
 \family typewriter 
 In [2]: /zip (1,2,3),(4,5,6)
 \newline 
 ------> zip ((1,2,3),(4,5,6)) 
 \newline 
 Out[2]= [(1, 4), (2, 5), (3, 6)] 
 \layout Standard
 
 IPython tells you that it has altered your command line by displaying the
  new command line preceded by 
 \family typewriter 
 -->
 \family default 
 .
  e.g.: 
 \layout Standard
 
 
 \family typewriter 
 In [18]: callable list
 \newline 
 -------> callable (list)
 \layout Subsubsection
 
 Automatic quoting 
 \layout Standard
 
 You can force automatic quoting of a function's arguments by using 
 \family typewriter 
 `,'
 \family default 
  or 
 \family typewriter 
 `;'
 \family default 
  as the first character of a line.
  For example: 
 \layout Standard
 
 
 \family typewriter 
 >>> ,my_function /home/me # becomes my_function("/home/me") 
 \layout Standard
 
 If you use 
 \family typewriter 
 `;'
 \family default 
  instead, the whole argument is quoted as a single string (while 
 \family typewriter 
 `,'
 \family default 
  splits on whitespace):
 \layout Standard
 
 
 \family typewriter 
 >>> ,my_function a b c # becomes my_function("a","b","c")
 \layout Standard
 
 
 \family typewriter 
 >>> ;my_function a b c # becomes my_function("a b c")
 \layout Standard
 
 Note that the `
 \family typewriter 
 ,
 \family default 
 ' or `
 \family typewriter 
 ;
 \family default 
 ' MUST be the first character on the line! This won't work: 
 \layout Standard
 
 
 \family typewriter 
 >>> x = ,my_function /home/me # syntax error
 \layout Section
 
 
 \begin_inset LatexCommand \label{sec:customization}
 
 \end_inset 
 
 Customization
 \layout Standard
 
 As we've already mentioned, IPython reads a configuration file which can
  be specified at the command line (
 \family typewriter 
 -rcfile
 \family default 
 ) or which by default is assumed to be called 
 \family typewriter 
 ipythonrc
 \family default 
 .
  Such a file is looked for in the current directory where IPython is started
  and then in your 
 \family typewriter 
 IPYTHONDIR
 \family default 
 , which allows you to have local configuration files for specific projects.
  In this section we will call these types of configuration files simply
  rcfiles (short for resource configuration file).
 \layout Standard
 
 The syntax of an rcfile is one of key-value pairs separated by whitespace,
  one per line.
  Lines beginning with a 
 \family typewriter 
 #
 \family default 
  are ignored as comments, but comments can 
 \series bold 
 not
 \series default 
  be put on lines with data (the parser is fairly primitive).
  Note that these are not python files, and this is deliberate, because it
  allows us to do some things which would be quite tricky to implement if
  they were normal python files.
 \layout Standard
 
 First, an rcfile can contain permanent default values for almost all command
  line options (except things like 
 \family typewriter 
 -help
 \family default 
  or 
 \family typewriter 
 -Version
 \family default 
 ).
  Sec\SpecialChar ~
 
 \begin_inset LatexCommand \ref{sec:cmd-line-opts}
 
 \end_inset 
 
  contains a description of all command-line options.
  However, values you explicitly specify at the command line override the
  values defined in the rcfile.
 \layout Standard
 
 Besides command line option values, the rcfile can specify values for certain
  extra special options which are not available at the command line.
  These options are briefly described below.
  
 \layout Standard
 
 Each of these options may appear as many times as you need it in the file.
 \layout List
 \labelwidthstring 00.00.0000
 
 
 \family typewriter 
 \series bold 
 include\SpecialChar ~
 <file1>\SpecialChar ~
 <file2>\SpecialChar ~
 ...
 \family default 
 \series default 
 : you can name 
 \emph on 
 other 
 \emph default 
 rcfiles you want to recursively load up to 15 levels (don't use the 
 \family typewriter 
 <>
 \family default 
  brackets in your names!).
  This feature allows you to define a 'base' rcfile with general options
  and special-purpose files which can be loaded only when needed with particular
  configuration options.
  To make this more convenient, IPython accepts the 
 \family typewriter 
 -profile <name>
 \family default 
  option (abbreviates to 
 \family typewriter 
 -p <name
 \family default 
 >)
 \family typewriter 
  which
 \family default 
  tells it to look for an rcfile named 
 \family typewriter 
 ipythonrc-<name>
 \family default 
 .
  
 \layout List
 \labelwidthstring 00.00.0000
 
 
 \family typewriter 
 \series bold 
 import_mod\SpecialChar ~
 <mod1>\SpecialChar ~
 <mod2>\SpecialChar ~
 ...
 \family default 
 \series default 
 : import modules with '
 \family typewriter 
 import
 \family default 
  
 \family typewriter 
 <mod1>,<mod2>,...
 \family default 
 ' 
 \layout List
 \labelwidthstring 00.00.0000
 
 
 \family typewriter 
 \series bold 
 import_some\SpecialChar ~
 <mod>\SpecialChar ~
 <f1>\SpecialChar ~
 <f2>\SpecialChar ~
 ...
 \family default 
 \series default 
 : import functions with '
 \family typewriter 
 from <mod> import
 \family default 
  
 \family typewriter 
 <f1>,<f2>,...
 \family default 
 ' 
 \layout List
 \labelwidthstring 00.00.0000
 
 
 \family typewriter 
 \series bold 
 import_all\SpecialChar ~
 <mod1>\SpecialChar ~
 <mod2>\SpecialChar ~
 ...
 \family default 
 \series default 
 : for each module listed import functions with '
 \family typewriter 
 from <mod> import *
 \family default 
 ' 
 \layout List
 \labelwidthstring 00.00.0000
 
 
 \family typewriter 
 \series bold 
 execute\SpecialChar ~
 <python\SpecialChar ~
 code>
 \family default 
 \series default 
 : give any single-line python code to be executed.
 \layout List
 \labelwidthstring 00.00.0000
 
 
 \family typewriter 
 \series bold 
 execfile\SpecialChar ~
 <filename>
 \family default 
 \series default 
 : execute the python file given with an '
 \family typewriter 
 execfile(filename)
 \family default 
 ' command.
  Username expansion is performed on the given names.
  So if you need any amount of extra fancy customization that won't fit in
  any of the above 'canned' options, you can just put it in a separate python
  file and execute it.
 \layout List
 \labelwidthstring 00.00.0000
 
 
 \family typewriter 
 \series bold 
 alias\SpecialChar ~
 <alias_def>
 \family default 
 \series default 
 : this is equivalent to calling '
 \family typewriter 
 %alias\SpecialChar ~
 <alias_def>
 \family default 
 ' at the IPython command line.
  This way, from within IPython you can do common system tasks without having
  to exit it or use the 
 \family typewriter 
 !
 \family default 
  escape.
  IPython isn't meant to be a shell replacement, but it is often very useful
  to be able to do things with files while testing code.
  This gives you the flexibility to have within IPython any aliases you may
  be used to under your normal system shell.
 \layout Subsection
 
 
 \begin_inset LatexCommand \label{sec:ipytonrc-sample}
 
 \end_inset 
 
 Sample 
 \family typewriter 
 ipythonrc
 \family default 
  file
 \layout Standard
 
 The default rcfile, called 
 \family typewriter 
 ipythonrc
 \family default 
  and supplied in your 
 \family typewriter 
 IPYTHONDIR 
 \family default 
 directory contains lots of comments on all of these options.
  We reproduce it here for reference:
 \layout Standard
 
 
 \begin_inset ERT
 status Open
 
 \layout Standard
 
 \backslash 
 codelist{../IPython/UserConfig/ipythonrc}
 \end_inset 
 
 
 \layout Subsection
 
 
 \begin_inset LatexCommand \label{sec:prompts}
 
 \end_inset 
 
 Fine-tuning your prompt
 \layout Standard
 
 IPython's prompts can be customized using a syntax similar to that of the
  
 \family typewriter 
 bash
 \family default 
  shell.
  Many of 
 \family typewriter 
 bash
 \family default 
 's escapes are supported, as well as a few additional ones.
  We list them below:
 \layout Description
 
 
 \backslash 
 # the prompt/history count number
 \layout Description
 
 
 \backslash 
 D the prompt/history count, with the actual digits replaced by dots.
  Used mainly in continuation prompts (prompt_in2)
 \layout Description
 
 
 \backslash 
 w the current working directory
 \layout Description
 
 
 \backslash 
 W the basename of current working directory
 \layout Description
 
 
 \backslash 
 X
 \emph on 
 n
 \emph default 
  where 
 \begin_inset Formula $n=0\ldots5.$
 \end_inset 
 
  The current working directory, with 
 \family typewriter 
 $HOME
 \family default 
  replaced by 
 \family typewriter 
 ~
 \family default 
 , and filtered out to contain only 
 \begin_inset Formula $n$
 \end_inset 
 
  path elements
 \layout Description
 
 
 \backslash 
 Y
 \emph on 
 n
 \emph default 
  Similar to 
 \backslash 
 X
 \emph on 
 n
 \emph default 
 , but with the 
 \begin_inset Formula $n+1$
 \end_inset 
 
  element included if it is 
 \family typewriter 
 ~
 \family default 
  (this is similar to the behavior of the %c
 \emph on 
 n
 \emph default 
  escapes in 
 \family typewriter 
 tcsh
 \family default 
 )
 \layout Description
 
 
 \backslash 
 u the username of the current user
 \layout Description
 
 
 \backslash 
 $ if the effective UID is 0, a #, otherwise a $
 \layout Description
 
 
 \backslash 
 h the hostname up to the first `.'
 \layout Description
 
 
 \backslash 
 H the hostname
 \layout Description
 
 
 \backslash 
 n a newline
 \layout Description
 
 
 \backslash 
 r a carriage return
 \layout Description
 
 
 \backslash 
 v IPython version string
 \layout Standard
 
 In addition to these, ANSI color escapes can be insterted into the prompts,
  as 
 \family typewriter 
 
 \backslash 
 C_
 \emph on 
 ColorName
 \family default 
 \emph default 
 .
  The list of valid color names is: Black, Blue, Brown, Cyan, DarkGray, Green,
  LightBlue, LightCyan, LightGray, LightGreen, LightPurple, LightRed, NoColor,
  Normal, Purple, Red, White, Yellow.
 \layout Standard
 
 Finally, IPython supports the evaluation of arbitrary expressions in your
  prompt string.
  The prompt strings are evaluated through the syntax of PEP 215, but basically
  you can use 
 \family typewriter 
 $x.y
 \family default 
  to expand the value of 
 \family typewriter 
 x.y
 \family default 
 , and for more complicated expressions you can use braces: 
 \family typewriter 
 ${foo()+x}
 \family default 
  will call function 
 \family typewriter 
 foo
 \family default 
  and add to it the value of 
 \family typewriter 
 x
 \family default 
 , before putting the result into your prompt.
  For example, using 
 \newline 
 
 \family typewriter 
 prompt_in1 '${commands.getoutput("uptime")}
 \backslash 
 nIn [
 \backslash 
 #]: '
 \newline 
 
 \family default 
 will print the result of the uptime command on each prompt (assuming the
  
 \family typewriter 
 commands
 \family default 
  module has been imported in your 
 \family typewriter 
 ipythonrc
 \family default 
  file).
 \layout Subsubsection
 
 Prompt examples
 \layout Standard
 
 The following options in an ipythonrc file will give you IPython's default
  prompts:
 \layout Standard
 
 
 \family typewriter 
 prompt_in1 'In [
 \backslash 
 #]:'
 \newline 
 prompt_in2 '\SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 .
 \backslash 
 D.:'
 \newline 
 prompt_out 'Out[
 \backslash 
 #]:'
 \layout Standard
 
 which look like this:
 \layout Standard
 
 
 \family typewriter 
 In [1]: 1+2
 \newline 
 Out[1]: 3
 \layout Standard
 
 
 \family typewriter 
 In [2]: for i in (1,2,3):
 \newline 
 
 \begin_inset ERT
 status Collapsed
 
 \layout Standard
 
 \backslash 
 hspace*{0mm}
 \end_inset 
 
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 ...: \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 print i,
 \newline 
 
 \begin_inset ERT
 status Collapsed
 
 \layout Standard
 
 \backslash 
 hspace*{0mm}
 \end_inset 
 
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 ...:
 \newline 
 1 2 3
 \layout Standard
 
 These will give you a very colorful prompt with path information:
 \layout Standard
 
 
 \family typewriter 
 #prompt_in1 '
 \backslash 
 C_Red
 \backslash 
 u
 \backslash 
 C_Blue[
 \backslash 
 C_Cyan
 \backslash 
 Y1
 \backslash 
 C_Blue]
 \backslash 
 C_LightGreen
 \backslash 
 #>'
 \newline 
 prompt_in2 ' ..
 \backslash 
 D>'
 \newline 
 prompt_out '<
 \backslash 
 #>' 
 \layout Standard
 
 which look like this:
 \layout Standard
 
 
 \family typewriter 
 \color red
 fperez
 \color blue
 [
 \color cyan
 ~/ipython
 \color blue
 ]
 \color green
 1>
 \color default
  1+2
 \newline 
 
 \begin_inset ERT
 status Collapsed
 
 \layout Standard
 
 \backslash 
 hspace*{0mm}
 \end_inset 
 
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 
 \color red
 <1>
 \color default
  3
 \newline 
 
 \color red
 fperez
 \color blue
 [
 \color cyan
 ~/ipython
 \color blue
 ]
 \color green
 2>
 \color default
  for i in (1,2,3):
 \newline 
 
 \begin_inset ERT
 status Collapsed
 
 \layout Standard
 
 \backslash 
 hspace*{0mm}
 \end_inset 
 
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 
 \color green
 ...>
 \color default
  \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 print i,
 \newline 
 
 \begin_inset ERT
 status Collapsed
 
 \layout Standard
 
 \backslash 
 hspace*{0mm}
 \end_inset 
 
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 
 \color green
 ...>
 \color default
 
 \newline 
 1 2 3
 \layout Standard
 
 The following shows the usage of dynamic expression evaluation:
 \layout Subsection
 
 
 \begin_inset LatexCommand \label{sec:profiles}
 
 \end_inset 
 
 IPython profiles
 \layout Standard
 
 As we already mentioned, IPython supports the 
 \family typewriter 
 -profile
 \family default 
  command-line option (see sec.
  
 \begin_inset LatexCommand \ref{sec:cmd-line-opts}
 
 \end_inset 
 
 ).
  A profile is nothing more than a particular configuration file like your
  basic 
 \family typewriter 
 ipythonrc
 \family default 
  one, but with particular customizations for a specific purpose.
  When you start IPython with '
 \family typewriter 
 ipython -profile <name>
 \family default 
 ', it assumes that in your 
 \family typewriter 
 IPYTHONDIR
 \family default 
  there is a file called 
 \family typewriter 
 ipythonrc-<name>
 \family default 
 , and loads it instead of the normal 
 \family typewriter 
 ipythonrc
 \family default 
 .
 \layout Standard
 
 This system allows you to maintain multiple configurations which load modules,
  set options, define functions, etc.
  suitable for different tasks and activate them in a very simple manner.
  In order to avoid having to repeat all of your basic options (common things
  that don't change such as your color preferences, for example), any profile
  can include another configuration file.
  The most common way to use profiles is then to have each one include your
  basic 
 \family typewriter 
 ipythonrc
 \family default 
  file as a starting point, and then add further customizations.
 \layout Standard
 
 In sections 
 \begin_inset LatexCommand \ref{sec:syntax-extensions}
 
 \end_inset 
 
  and 
 \begin_inset LatexCommand \ref{sec:Gnuplot}
 
 \end_inset 
 
  we discuss some particular profiles which come as part of the standard
  IPython distribution.
  You may also look in your 
 \family typewriter 
 IPYTHONDIR
 \family default 
  directory, any file whose name begins with 
 \family typewriter 
 ipythonrc-
 \family default 
  is a profile.
  You can use those as examples for further customizations to suit your own
  needs.
 \layout Section
 
 
 \begin_inset OptArg
 collapsed false
 
 \layout Standard
 
 IPython as default...
 \end_inset 
 
 IPython as your default Python environment
 \layout Standard
 
 Python honors the environment variable 
 \family typewriter 
 PYTHONSTARTUP 
 \family default 
 and will execute at startup the file referenced by this variable.
  If you put at the end of this file the following two lines of code:
 \layout Standard
 
 
 \family typewriter 
 import IPython
 \newline 
 IPython.Shell.IPShell().mainloop(sys_exit=1)
 \layout Standard
 
 then IPython will be your working environment anytime you start Python.
  The 
 \family typewriter 
 sys_exit=1
 \family default 
  is needed to have IPython issue a call to 
 \family typewriter 
 sys.exit()
 \family default 
  when it finishes, otherwise you'll be back at the normal Python '
 \family typewriter 
 >>>
 \family default 
 ' prompt
 \begin_inset Foot
 collapsed true
 
 \layout Standard
 
 Based on an idea by Holger Krekel.
 \end_inset 
 
 .
 \layout Standard
 
 This is probably useful to developers who manage multiple Python versions
  and don't want to have correspondingly multiple IPython versions.
  Note that in this mode, there is no way to pass IPython any command-line
  options, as those are trapped first by Python itself.
 \layout Section
 
 
 \begin_inset LatexCommand \label{sec:embed}
 
 \end_inset 
 
 Embedding IPython
 \layout Standard
 
 It is possible to start an IPython instance 
 \emph on 
 inside
 \emph default 
  your own Python programs.
  This allows you to evaluate 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
  
 \emph on 
 not
 \emph default 
  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.
 \layout Standard
 
 This feature allows you to easily have a fully functional python environment
  for doing object introspection anywhere in your code with a simple function
  call.
  In some cases a simple print statement is enough, but if you need to do
  more detailed analysis of a code fragment this feature can be very valuable.
 \layout Standard
 
 It can also be useful in scientific computing situations where it is common
  to need to do some automatic, computationally intensive part and then stop
  to look at data, plots, etc
 \begin_inset Foot
 collapsed true
 
 \layout Standard
 
 This functionality was inspired by IDL's combination of the 
 \family typewriter 
 stop
 \family default 
  keyword and the 
 \family typewriter 
 .continue
 \family default 
  executive command, which I have found very useful in the past, and by a
  posting on comp.lang.python by cmkl <cmkleffner-AT-gmx.de> on Dec.
  06/01 concerning similar uses of pyrepl.
 \end_inset 
 
 .
  Opening an IPython instance will give you full access to your data and
  functions, and you can resume program execution once you are done with
  the interactive part (perhaps to stop again later, as many times as needed).
 \layout Standard
 
 The following code snippet is the bare minimum you need to include in your
  Python programs for this to work (detailed examples follow later):
 \layout LyX-Code
 
 from IPython.Shell import IPShellEmbed
 \layout LyX-Code
 
 ipshell = IPShellEmbed()
 \layout LyX-Code
 
 ipshell() # this call anywhere in your program will start IPython
 \layout Standard
 
 You can run embedded instances even in code which is itself being run at
  the IPython interactive prompt with '
 \family typewriter 
 %run\SpecialChar ~
 <filename>
 \family default 
 '.
  Since it's easy to get lost as to where you are (in your top-level IPython
  or in your embedded one), it's a good idea in such cases to set the in/out
  prompts to something different for the embedded instances.
  The code examples below illustrate this.
 \layout Standard
 
 You can also have multiple IPython instances in your program and open them
  separately, for example with different options for data presentation.
  If you close and open the same instance multiple times, its prompt counters
  simply continue from each execution to the next.
 \layout Standard
 
 Please look at the docstrings in the 
 \family typewriter 
 Shell.py
 \family default 
  module for more details on the use of this system.
 \layout Standard
 
 The following sample file illustrating how to use the embedding functionality
  is provided in the examples directory as 
 \family typewriter 
 example-embed.py
 \family default 
 .
  It should be fairly self-explanatory:
 \layout Standard
 
 
 \begin_inset ERT
 status Open
 
 \layout Standard
 
 \backslash 
 codelist{examples/example-embed.py}
 \end_inset 
 
 
 \layout Standard
 
 Once you understand how the system functions, you can use the following
  code fragments in your programs which are ready for cut and paste:
 \layout Standard
 
 
 \begin_inset ERT
 status Open
 
 \layout Standard
 
 \backslash 
 codelist{examples/example-embed-short.py}
 \end_inset 
 
 
 \layout Section
 
 
 \begin_inset LatexCommand \label{sec:using-pdb}
 
 \end_inset 
 
 Using the Python debugger (
 \family typewriter 
 pdb
 \family default 
 )
 \layout Subsection
 
 Running entire programs via 
 \family typewriter 
 pdb
 \layout Standard
 
 
 \family typewriter 
 pdb
 \family default 
 , the Python debugger, is a powerful interactive debugger which allows you
  to step through code, set breakpoints, watch variables, etc.
  IPython makes it very easy to start any script under the control of 
 \family typewriter 
 pdb
 \family default 
 , regardless of whether you have wrapped it into a 
 \family typewriter 
 `main()'
 \family default 
  function or not.
  For this, simply type 
 \family typewriter 
 `%run -d myscript'
 \family default 
  at an IPython prompt.
  See the 
 \family typewriter 
 %run
 \family default 
  command's documentation (via 
 \family typewriter 
 `%run?'
 \family default 
  or in Sec.\SpecialChar ~
 
 \begin_inset LatexCommand \ref{sec:magic}
 
 \end_inset 
 
 ) for more details, including how to control where 
 \family typewriter 
 pdb
 \family default 
  will stop execution first.
 \layout Standard
 
 For more information on the use of the 
 \family typewriter 
 pdb
 \family default 
  debugger, read the included 
 \family typewriter 
 pdb.doc
 \family default 
  file (part of the standard Python distribution).
  On a stock Linux system it is located at 
 \family typewriter 
 /usr/lib/python2.3/pdb.doc
 \family default 
 , but the easiest way to read it is by using the 
 \family typewriter 
 help()
 \family default 
  function of the 
 \family typewriter 
 pdb
 \family default 
  module as follows (in an IPython prompt):
 \layout Standard
 
 
 \family typewriter 
 In [1]: import pdb
 \newline 
 In [2]: pdb.help()
 \layout Standard
 
 This will load the 
 \family typewriter 
 pdb.doc
 \family default 
  document in a file viewer for you automatically.
 \layout Subsection
 
 Automatic invocation of 
 \family typewriter 
 pdb
 \family default 
  on exceptions
 \layout Standard
 
 IPython, if started with the 
 \family typewriter 
 -pdb
 \family default 
  option (or if the option is set in your rc file) can call the Python 
 \family typewriter 
 pdb
 \family default 
  debugger every time your code triggers an uncaught exception
 \begin_inset Foot
 collapsed true
 
 \layout Standard
 
 Many thanks to Christopher Hart for the request which prompted adding this
  feature to IPython.
 \end_inset 
 
 .
  This feature can also be toggled at any time with the 
 \family typewriter 
 %pdb
 \family default 
  magic command.
  This can be extremely useful in order to find the origin of subtle bugs,
  because 
 \family typewriter 
 pdb
 \family default 
  opens up at the point in your code which triggered the exception, and while
  your program is at this point `dead', all the data is still available and
  you can walk up and down the stack frame and understand the origin of the
  problem.
 \layout Standard
 
 Furthermore, you can use these debugging facilities both with the embedded
  IPython mode and without IPython at all.
  For an embedded shell (see sec.
  
 \begin_inset LatexCommand \ref{sec:embed}
 
 \end_inset 
 
 ), simply call the constructor with 
 \family typewriter 
 `-pdb'
 \family default 
  in the argument string and automatically 
 \family typewriter 
 pdb
 \family default 
  will be called if an uncaught exception is triggered by your code.
  
 \layout Standard
 
 For stand-alone use of the feature in your programs which do not use IPython
  at all, put the following lines toward the top of your `main' routine:
 \layout Standard
 \align left 
 
 \family typewriter 
 import sys,IPython.ultraTB 
 \newline 
 sys.excepthook = IPython.ultraTB.FormattedTB(mode=`Verbose', color_scheme=`Linux',
  call_pdb=1)
 \layout Standard
 
 The 
 \family typewriter 
 mode
 \family default 
  keyword can be either 
 \family typewriter 
 `Verbose'
 \family default 
  or 
 \family typewriter 
 `Plain'
 \family default 
 , giving either very detailed or normal tracebacks respectively.
  The 
 \family typewriter 
 color_scheme
 \family default 
  keyword can be one of 
 \family typewriter 
 `NoColor'
 \family default 
 , 
 \family typewriter 
 `Linux'
 \family default 
  (default) or 
 \family typewriter 
 `LightBG'
 \family default 
 .
  These are the same options which can be set in IPython with 
 \family typewriter 
 -colors
 \family default 
  and 
 \family typewriter 
 -xmode
 \family default 
 .
 \layout Standard
 
 This will give any of your programs detailed, colored tracebacks with automatic
  invocation of 
 \family typewriter 
 pdb
 \family default 
 .
 \layout Section
 
 
 \begin_inset LatexCommand \label{sec:syntax-extensions}
 
 \end_inset 
 
 Extensions for syntax processing
 \layout Standard
 
 This isn't for the faint of heart, because the potential for breaking things
  is quite high.
  But it can be a very powerful and useful feature.
  In a nutshell, you can redefine the way IPython processes the user input
  line to accept new, special extensions to the syntax without needing to
  change any of IPython's own code.
 \layout Standard
 
 In the 
 \family typewriter 
 IPython/Extensions
 \family default 
  directory you will find some examples supplied, which we will briefly describe
  now.
  These can be used `as is' (and both provide very useful functionality),
  or you can use them as a starting point for writing your own extensions.
 \layout Subsection
 
 Pasting of code starting with 
 \family typewriter 
 `>>> 
 \family default 
 ' or 
 \family typewriter 
 `...
  
 \family default 
 '
 \layout Standard
 
 In the python tutorial it is common to find code examples which have been
  taken from real python sessions.
  The problem with those is that all the lines begin with either 
 \family typewriter 
 `>>> 
 \family default 
 ' or 
 \family typewriter 
 `...
  
 \family default 
 ', which makes it impossible to paste them all at once.
  One must instead do a line by line manual copying, carefully removing the
  leading extraneous characters.
 \layout Standard
 
 This extension identifies those starting characters and removes them from
  the input automatically, so that one can paste multi-line examples directly
  into IPython, saving a lot of time.
  Please look at the file 
 \family typewriter 
 InterpreterPasteInput.py
 \family default 
  in the 
 \family typewriter 
 IPython/Extensions
 \family default 
  directory for details on how this is done.
 \layout Standard
 
 IPython comes with a special profile enabling this feature, called 
 \family typewriter 
 tutorial
 \family default 
 \emph on 
 .
 
 \emph default 
  Simply start IPython via 
 \family typewriter 
 `ipython\SpecialChar ~
 -p\SpecialChar ~
 tutorial'
 \family default 
  and the feature will be available.
  In a normal IPython session you can activate the feature by importing the
  corresponding module with:
 \newline 
 
 \family typewriter 
 In [1]: import IPython.Extensions.InterpreterPasteInput
 \layout Standard
 
 The following is a 'screenshot' of how things work when this extension is
  on, copying an example from the standard tutorial:
 \layout Standard
 
 
 \family typewriter 
 IPython profile: tutorial
 \newline 
 \SpecialChar ~
 
 \newline 
 *** Pasting of code with ">>>" or "..." has been enabled.
 \newline 
 \SpecialChar ~
 
 \newline 
 In [1]: >>> def fib2(n): # return Fibonacci series up to n
 \newline 
 
 \begin_inset ERT
 status Collapsed
 
 \layout Standard
 
 \backslash 
 hspace*{0mm}
 \end_inset 
 
 \SpecialChar ~
 \SpecialChar ~
  ...: ...\SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
  """Return a list containing the Fibonacci series up to n."""
 \newline 
 
 \begin_inset ERT
 status Collapsed
 
 \layout Standard
 
 \backslash 
 hspace*{0mm}
 \end_inset 
 
 \SpecialChar ~
 \SpecialChar ~
  ...: ...\SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
  result = []
 \newline 
 
 \begin_inset ERT
 status Collapsed
 
 \layout Standard
 
 \backslash 
 hspace*{0mm}
 \end_inset 
 
 \SpecialChar ~
 \SpecialChar ~
  ...: ...\SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
  a, b = 0, 1
 \newline 
 
 \begin_inset ERT
 status Collapsed
 
 \layout Standard
 
 \backslash 
 hspace*{0mm}
 \end_inset 
 
 \SpecialChar ~
 \SpecialChar ~
  ...: ...\SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
  while b < n:
 \newline 
 
 \begin_inset ERT
 status Collapsed
 
 \layout Standard
 
 \backslash 
 hspace*{0mm}
 \end_inset 
 
 \SpecialChar ~
 \SpecialChar ~
  ...: ...\SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
  result.append(b)\SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
  # see below
 \newline 
 
 \begin_inset ERT
 status Collapsed
 
 \layout Standard
 
 \backslash 
 hspace*{0mm}
 \end_inset 
 
 \SpecialChar ~
 \SpecialChar ~
  ...: ...\SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
  a, b = b, a+b
 \newline 
 
 \begin_inset ERT
 status Collapsed
 
 \layout Standard
 
 \backslash 
 hspace*{0mm}
 \end_inset 
 
 \SpecialChar ~
 \SpecialChar ~
  ...: ...\SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
  return result
 \newline 
 
 \begin_inset ERT
 status Collapsed
 
 \layout Standard
 
 \backslash 
 hspace*{0mm}
 \end_inset 
 
 \SpecialChar ~
 \SpecialChar ~
  ...:
 \newline 
 \SpecialChar ~
 
 \newline 
 In [2]: fib2(10)
 \newline 
 Out[2]: [1, 1, 2, 3, 5, 8]
 \layout Standard
 
 Note that as currently written, this extension does 
 \emph on 
 not 
 \emph default 
 recognize IPython's prompts for pasting.
  Those are more complicated, since the user can change them very easily,
  they involve numbers and can vary in length.
  One could however extract all the relevant information from the IPython
  instance and build an appropriate regular expression.
  This is left as an exercise for the reader.
 \layout Subsection
 
 Input of physical quantities with units
 \layout Standard
 
 The module 
 \family typewriter 
 PhysicalQInput
 \family default 
  allows a simplified form of input for physical quantities with units.
  This file is meant to be used in conjunction with the 
 \family typewriter 
 PhysicalQInteractive
 \family default 
  module (in the same directory) and 
 \family typewriter 
 Physics.PhysicalQuantities
 \family default 
  from Konrad Hinsen's ScientificPython (
 \begin_inset LatexCommand \htmlurl{http://dirac.cnrs-orleans.fr/ScientificPython/}
 
 \end_inset 
 
 ).
 \layout Standard
 
 The 
 \family typewriter 
 Physics.PhysicalQuantities
 \family default 
  module defines 
 \family typewriter 
 PhysicalQuantity
 \family default 
  objects, but these must be declared as instances of a class.
  For example, to define 
 \family typewriter 
 v
 \family default 
  as a velocity of 3\SpecialChar ~
 m/s, normally you would write:
 \family typewriter 
 
 \newline 
 In [1]: v = PhysicalQuantity(3,'m/s')
 \layout Standard
 
 Using the 
 \family typewriter 
 PhysicalQ_Input
 \family default 
  extension this can be input instead as:
 \family typewriter 
 
 \newline 
 In [1]: v = 3 m/s
 \family default 
 
 \newline 
 which is much more convenient for interactive use (even though it is blatantly
  invalid Python syntax).
 \layout Standard
 
 The 
 \family typewriter 
 physics
 \family default 
  profile supplied with IPython (enabled via 
 \family typewriter 
 'ipython -p physics'
 \family default 
 ) uses these extensions, which you can also activate with:
 \layout Standard
 
 
 \family typewriter 
 from math import * # math MUST be imported BEFORE PhysicalQInteractive
 \newline 
 from IPython.Extensions.PhysicalQInteractive import *
 \newline 
 import IPython.Extensions.PhysicalQInput
 \layout Section
 
 
 \begin_inset LatexCommand \label{sec:IPython-as-shell}
 
 \end_inset 
 
 IPython as a system shell
 \layout Standard
 
 IPython ships with a special profile called 
 \family typewriter 
 pysh
 \family default 
 , which you can activate at the command line as 
 \family typewriter 
 `ipython -p pysh'
 \family default 
 .
  This loads 
 \family typewriter 
 InterpreterExec
 \family default 
 , along with some additional facilities and a prompt customized for filesystem
  navigation.
 \layout Standard
 
 Note that this does 
 \emph on 
 not
 \emph default 
  make IPython a full-fledged system shell.
  In particular, it has no job control, so if you type Ctrl-Z (under Unix),
  you'll suspend pysh itself, not the process you just started.
  
 \layout Standard
 
 What the shell profile allows you to do is to use the convenient and powerful
  syntax of Python to do quick scripting at the command line.
  Below we describe some of its features.
 \layout Subsection
 
 Aliases
 \layout Standard
 
 All of your 
 \family typewriter 
 $PATH
 \family default 
  has been loaded as IPython aliases, so you should be able to type any normal
  system command and have it executed.
  See 
 \family typewriter 
 %alias?
 \family default 
  and 
 \family typewriter 
 %unalias?
 \family default 
  for details on the alias facilities.
  See also 
 \family typewriter 
 %rehash?
 \family default 
  and 
 \family typewriter 
 %rehashx? 
 \family default 
 for details on the mechanism used to load 
 \family typewriter 
 $PATH
 \family default 
 .
 \layout Subsection
 
 Special syntax
 \layout Standard
 
 Any lines which begin with 
 \family typewriter 
 `~'
 \family default 
 , 
 \family typewriter 
 `/'
 \family default 
  and 
 \family typewriter 
 `.'
 \family default 
  will be executed as shell commands instead of as Python code.
  The special escapes below are also recognized.
  
 \family typewriter 
 !cmd
 \family default 
  is valid in single or multi-line input, all others are only valid in single-lin
 e input:
 \layout Description
 
 
 \family typewriter 
 !cmd
 \family default 
  pass `cmd' directly to the shell 
 \layout Description
 
 
 \family typewriter 
 !!cmd
 \family default 
  execute `cmd' and return output as a list (split on `
 \backslash 
 n') 
 \layout Description
 
 
 \family typewriter 
 $var=cmd
 \family default 
  capture output of cmd into var, as a string 
 \layout Description
 
 
 \family typewriter 
 $$var=cmd
 \family default 
  capture output of cmd into var, as a list (split on `
 \backslash 
 n')
 \layout Standard
 
 The 
 \family typewriter 
 $
 \family default 
 /
 \family typewriter 
 $$
 \family default 
  syntaxes make Python variables from system output, which you can later
  use for further scripting.
  The converse is also possible: when executing an alias or calling to the
  system via 
 \family typewriter 
 !
 \family default 
 /
 \family typewriter 
 !!
 \family default 
 , you can expand any python variable or expression by prepending it with
  
 \family typewriter 
 $
 \family default 
 .
  Full details of the allowed syntax can be found in Python's PEP 215.
 \layout Standard
 
 A few brief examples will illustrate these (note that the indentation below
  may be incorrectly displayed):
 \layout Standard
 
 
 \family typewriter 
 fperez[~/test]|3> !ls *s.py 
 \newline 
 scopes.py strings.py
 \layout Standard
 
 ls is an internal alias, so there's no need to use 
 \family typewriter 
 !
 \family default 
 : 
 \layout Standard
 
 
 \family typewriter 
 fperez[~/test]|4> ls *s.py 
 \newline 
 scopes.py* strings.py
 \layout Standard
 
 !!ls will return the output into a Python variable: 
 \layout Standard
 
 
 \family typewriter 
 fperez[~/test]|5> !!ls *s.py 
 \newline 
 
 \begin_inset ERT
 status Collapsed
 
 \layout Standard
 
 \backslash 
 hspace*{0mm}
 \end_inset 
 
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 <5> ['scopes.py', 'strings.py'] 
 \newline 
 fperez[~/test]|6> print _5 
 \newline 
 ['scopes.py', 'strings.py']
 \layout Standard
 
 
 \family typewriter 
 $
 \family default 
  and 
 \family typewriter 
 $$
 \family default 
  allow direct capture to named variables: 
 \layout Standard
 
 
 \family typewriter 
 fperez[~/test]|7> $astr = ls *s.py 
 \newline 
 fperez[~/test]|8> astr 
 \newline 
 
 \begin_inset ERT
 status Collapsed
 
 \layout Standard
 
 \backslash 
 hspace*{0mm}
 \end_inset 
 
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 <8> 'scopes.py
 \backslash 
 nstrings.py'
 \layout Standard
 
 
 \family typewriter 
 fperez[~/test]|9> $$alist = ls *s.py 
 \newline 
 fperez[~/test]|10> alist 
 \newline 
 
 \begin_inset ERT
 status Collapsed
 
 \layout Standard
 
 \backslash 
 hspace*{0mm}
 \end_inset 
 
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 <10> ['scopes.py', 'strings.py']
 \layout Standard
 
 alist is now a normal python list you can loop over.
  Using 
 \family typewriter 
 $
 \family default 
  will expand back the python values when alias calls are made:
 \layout Standard
 
 
 \family typewriter 
 fperez[~/test]|11> for f in alist: 
 \newline 
 
 \begin_inset ERT
 status Collapsed
 
 \layout Standard
 
 \backslash 
 hspace*{0mm}
 \end_inset 
 
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 |..> \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 print 'file',f, 
 \newline 
 
 \begin_inset ERT
 status Collapsed
 
 \layout Standard
 
 \backslash 
 hspace*{0mm}
 \end_inset 
 
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 |..> \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 wc -l $f 
 \newline 
 
 \begin_inset ERT
 status Collapsed
 
 \layout Standard
 
 \backslash 
 hspace*{0mm}
 \end_inset 
 
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 |..> 
 \newline 
 file scopes.py 13 scopes.py 
 \newline 
 file strings.py 4 strings.py
 \layout Standard
 
 Note that you may need to protect your variables with braces if you want
  to append strings to their names.
  To copy all files in alist to 
 \family typewriter 
 .bak
 \family default 
  extensions, you must use: 
 \layout Standard
 
 
 \family typewriter 
 fperez[~/test]|12> for f in alist: 
 \newline 
 
 \begin_inset ERT
 status Collapsed
 
 \layout Standard
 
 \backslash 
 hspace*{0mm}
 \end_inset 
 
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 |..> \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 cp $f ${f}.bak
 \layout Standard
 
 If you try using 
 \family typewriter 
 $f.bak
 \family default 
 , you'll get an AttributeError exception saying that your string object
  doesn't have a 
 \family typewriter 
 .bak
 \family default 
  attribute.
  This is because the 
 \family typewriter 
 $
 \family default 
  expansion mechanism allows you to expand full Python expressions: 
 \layout Standard
 
 
 \family typewriter 
 fperez[~/test]|13> echo "sys.platform is: $sys.platform" 
 \newline 
 sys.platform is: linux2
 \layout Standard
 
 IPython's input history handling is still active, which allows you to rerun
  a single block of multi-line input by simply using exec: 
 \newline 
 
 \family typewriter 
 fperez[~/test]|14> $$alist = ls *.eps 
 \newline 
 fperez[~/test]|15> exec _i11 
 \newline 
 file image2.eps 921 image2.eps 
 \newline 
 file image.eps 921 image.eps
 \layout Standard
 
 While these are new special-case syntaxes, they are designed to allow very
  efficient use of the shell with minimal typing.
  At an interactive shell prompt, conciseness of expression wins over readability.
 \layout Subsection
 
 Useful functions and modules
 \layout Standard
 
 The os, sys and shutil modules from the Python standard library are automaticall
 y loaded.
  Some additional functions, useful for shell usage, are listed below.
  You can request more help about them with `
 \family typewriter 
 ?
 \family default 
 '.
 \layout Description
 
 
 \family typewriter 
 shell
 \family default 
  - execute a command in the underlying system shell 
 \layout Description
 
 
 \family typewriter 
 system
 \family default 
  - like 
 \family typewriter 
 shell()
 \family default 
 , but return the exit status of the command
 \layout Description
 
 
 \family typewriter 
 sout
 \family default 
  - capture the output of a command as a string
 \layout Description
 
 
 \family typewriter 
 lout
 \family default 
  - capture the output of a command as a list (split on `
 \backslash 
 n')
 \layout Description
 
 
 \family typewriter 
 getoutputerror
 \family default 
  - capture (output,error) of a shell commandss
 \layout Standard
 
 
 \family typewriter 
 sout
 \family default 
 /
 \family typewriter 
 lout
 \family default 
  are the functional equivalents of 
 \family typewriter 
 $
 \family default 
 /
 \family typewriter 
 $$
 \family default 
 .
  They are provided to allow you to capture system output in the middle of
  true python code, function definitions, etc (where 
 \family typewriter 
 $
 \family default 
  and 
 \family typewriter 
 $$
 \family default 
  are invalid).
 \layout Subsection
 
 Directory management
 \layout Standard
 
 Since each command passed by pysh to the underlying system is executed in
  a subshell which exits immediately, you can NOT use !cd to navigate the
  filesystem.
 \layout Standard
 
 Pysh provides its own builtin 
 \family typewriter 
 `%cd
 \family default 
 ' magic command to move in the filesystem (the 
 \family typewriter 
 %
 \family default 
  is not required with automagic on).
  It also maintains a list of visited directories (use 
 \family typewriter 
 %dhist
 \family default 
  to see it) and allows direct switching to any of them.
  Type 
 \family typewriter 
 `cd?
 \family default 
 ' for more details.
 \layout Standard
 
 
 \family typewriter 
 %pushd
 \family default 
 , 
 \family typewriter 
 %popd
 \family default 
  and 
 \family typewriter 
 %dirs
 \family default 
  are provided for directory stack handling.
 \layout Subsection
 
 Prompt customization
 \layout Standard
 
 The supplied 
 \family typewriter 
 ipythonrc-pysh
 \family default 
  profile comes with an example of a very colored and detailed prompt, mainly
  to serve as an illustration.
  The valid escape sequences, besides color names, are:
 \layout Description
 
 
 \backslash 
 # - Prompt number.
 \layout Description
 
 
 \backslash 
 D - Dots, as many as there are digits in 
 \backslash 
 # (so they align).
 \layout Description
 
 
 \backslash 
 w - Current working directory (cwd).
 \layout Description
 
 
 \backslash 
 W - Basename of current working directory.
 \layout Description
 
 
 \backslash 
 X
 \emph on 
 N
 \emph default 
  - Where 
 \emph on 
 N
 \emph default 
 =0..5.
  N terms of the cwd, with $HOME written as ~.
 \layout Description
 
 
 \backslash 
 Y
 \emph on 
 N
 \emph default 
  - Where 
 \emph on 
 N
 \emph default 
 =0..5.
  Like X
 \emph on 
 N
 \emph default 
 , but if ~ is term 
 \emph on 
 N
 \emph default 
 +1 it's also shown.
 \layout Description
 
 
 \backslash 
 u - Username.
 \layout Description
 
 
 \backslash 
 H - Full hostname.
 \layout Description
 
 
 \backslash 
 h - Hostname up to first '.'
 \layout Description
 
 
 \backslash 
 $ - Root symbol ($ or #).
  
 \layout Description
 
 
 \backslash 
 t - Current time, in H:M:S format.
 \layout Description
 
 
 \backslash 
 v - IPython release version.
  
 \layout Description
 
 
 \backslash 
 n - Newline.
  
 \layout Description
 
 
 \backslash 
 r - Carriage return.
  
 \layout Description
 
 
 \backslash 
 
 \backslash 
  - An explicitly escaped '
 \backslash 
 '.
 \layout Standard
 
 You can configure your prompt colors using any ANSI color escape.
  Each color escape sets the color for any subsequent text, until another
  escape comes in and changes things.
  The valid color escapes are:
 \layout Description
 
 
 \backslash 
 C_Black
 \layout Description
 
 
 \backslash 
 C_Blue
 \layout Description
 
 
 \backslash 
 C_Brown
 \layout Description
 
 
 \backslash 
 C_Cyan
 \layout Description
 
 
 \backslash 
 C_DarkGray
 \layout Description
 
 
 \backslash 
 C_Green
 \layout Description
 
 
 \backslash 
 C_LightBlue
 \layout Description
 
 
 \backslash 
 C_LightCyan
 \layout Description
 
 
 \backslash 
 C_LightGray
 \layout Description
 
 
 \backslash 
 C_LightGreen
 \layout Description
 
 
 \backslash 
 C_LightPurple
 \layout Description
 
 
 \backslash 
 C_LightRed
 \layout Description
 
 
 \backslash 
 C_Purple
 \layout Description
 
 
 \backslash 
 C_Red
 \layout Description
 
 
 \backslash 
 C_White
 \layout Description
 
 
 \backslash 
 C_Yellow
 \layout Description
 
 
 \backslash 
 C_Normal Stop coloring, defaults to your terminal settings.
 \layout Section
 
 
 \begin_inset LatexCommand \label{sec:Threading-support}
 
 \end_inset 
 
 Threading support
 \layout Standard
 
 
 \series bold 
 WARNING: 
 \series default 
 The threading support is still somewhat experimental, and it has only seen
  reasonable testing under Linux.
  Threaded code is particularly tricky to debug, and it tends to show extremely
  platform-dependent behavior.
  Since I only have access to Linux machines, I will have to rely on user's
  experiences and assistance for this area of IPython to improve under other
  platforms.
 \layout Standard
 
 IPython, via the 
 \family typewriter 
 -gthread
 \family default 
  , 
 \family typewriter 
 -qthread
 \family default 
  and 
 \family typewriter 
 -wthread
 \family default 
  options (described in Sec.\SpecialChar ~
 
 \begin_inset LatexCommand \ref{sec:threading-opts}
 
 \end_inset 
 
 ), can run in multithreaded mode to support pyGTK, Qt and WXPython applications
  respectively.
  These GUI toolkits need to control the python main loop of execution, so
  under a normal Python interpreter, starting a pyGTK, Qt or WXPython application
  will immediately freeze the shell.
  
 \layout Standard
 
 IPython, with one of these options (you can only use one at a time), separates
  the graphical loop and IPython's code execution run into different threads.
  This allows you to test interactively (with 
 \family typewriter 
 %run
 \family default 
 , for example) your GUI code without blocking.
 \layout Standard
 
 A nice mini-tutorial on using IPython along with the Qt Designer application
  is available at the SciPy wiki: 
 \begin_inset LatexCommand \htmlurl{http://www.scipy.org/Cookbook/Matplotlib/Qt_with_IPython_and_Designer}
 
 \end_inset 
 
 .
 \layout Subsection
 
 Tk issues
 \layout Standard
 
 As indicated in Sec.\SpecialChar ~
 
 \begin_inset LatexCommand \ref{sec:threading-opts}
 
 \end_inset 
 
 , a special 
 \family typewriter 
 -tk
 \family default 
  option is provided to try and allow Tk graphical applications to coexist
  interactively with WX, Qt or GTK ones.
  Whether this works at all, however, is very platform and configuration
  dependent.
  Please experiment with simple test cases before committing to using this
  combination of Tk and GTK/Qt/WX threading in a production environment.
 \layout Subsection
 
 Signals and Threads
 \layout Standard
 
 When any of the thread systems (GTK, Qt or WX) are active, either directly
  or via 
 \family typewriter 
 -pylab
 \family default 
  with a threaded backend, it is impossible to interrupt long-running Python
  code via 
 \family typewriter 
 Ctrl-C
 \family default 
 .
  IPython can not pass the KeyboardInterrupt exception (or the underlying
  
 \family typewriter 
 SIGINT
 \family default 
 ) 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.
 \layout Standard
 
 To the best of my knowledge, this limitation is imposed by the Python interprete
 r 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 
 \family typewriter 
 Shell.py
 \family default 
  module, and in particular at the 
 \family typewriter 
 runcode()
 \family default 
  method.
  
 \layout Subsection
 
 I/O pitfalls
 \layout Standard
 
 Be mindful that the Python interpreter switches between threads every 
 \begin_inset Formula $N$
 \end_inset 
 
  bytecodes, where the default value as of Python\SpecialChar ~
 2.3 is 
 \begin_inset Formula $N=100.$
 \end_inset 
 
  This value can be read by using the 
 \family typewriter 
 sys.getcheckinterval()
 \family default 
  function, and it can be reset via 
 \family typewriter 
 sys.setcheckinterval(
 \emph on 
 N
 \emph default 
 )
 \family default 
 .
  This switching of threads can cause subtly confusing effects if one of
  your threads is doing file I/O.
  In text mode, most systems only flush file buffers when they encounter
  a 
 \family typewriter 
 `
 \backslash 
 n'
 \family default 
 .
  An instruction as simple as
 \family typewriter 
 
 \newline 
 \SpecialChar ~
 \SpecialChar ~
 print >> filehandle, 
 \begin_inset Quotes eld
 \end_inset 
 
 hello world
 \begin_inset Quotes erd
 \end_inset 
 
 
 \family default 
 
 \newline 
 actually consists of several bytecodes, so it is possible that the newline
  does not reach your file before the next thread switch.
  Similarly, if you are writing to a file in binary mode, the file won't
  be flushed until the buffer fills, and your other thread may see apparently
  truncated files.
  
 \layout Standard
 
 For this reason, if you are using IPython's thread support and have (for
  example) a GUI application which will read data generated by files written
  to from the IPython thread, the safest approach is to open all of your
  files in unbuffered mode (the third argument to the 
 \family typewriter 
 file/open
 \family default 
  function is the buffering value):
 \newline 
 
 \family typewriter 
 \SpecialChar ~
 \SpecialChar ~
 filehandle = open(filename,mode,0)
 \layout Standard
 
 This is obviously a brute force way of avoiding race conditions with the
  file buffering.
  If you want to do it cleanly, and you have a resource which is being shared
  by the interactive IPython loop and your GUI thread, you should really
  handle it with thread locking and syncrhonization properties.
  The Python documentation discusses these.
 \layout Section
 
 
 \begin_inset LatexCommand \label{sec:interactive-demos}
 
 \end_inset 
 
 Interactive demos with IPython
 \layout Standard
 
 IPython ships with a basic system for running scripts interactively in sections,
  useful when presenting code to audiences.
  A few tags embedded in comments (so that the script remains valid Python
  code) divide a file into separate blocks, and the demo can be run one block
  at a time, with IPython printing (with syntax highlighting) the block before
  executing it, and returning to the interactive prompt after each block.
  The interactive namespace is updated after each block is run with the contents
  of the demo's namespace.
 \layout Standard
 
 This allows you to show a piece of code, run it and then execute interactively
  commands based on the variables just created.
  Once you want to continue, you simply execute the next block of the demo.
  The following listing shows the markup necessary for dividing a script
  into sections for execution as a demo.
 \layout Standard
 
 
 \begin_inset ERT
 status Open
 
 \layout Standard
 
 \backslash 
 codelist{examples/example-demo.py}
 \end_inset 
 
 
 \layout Standard
 
 In order to run a file as a demo, you must first make a 
 \family typewriter 
 Demo
 \family default 
  object out of it.
  If the file is named 
 \family typewriter 
 myscript.py
 \family default 
 , the following code will make a demo:
 \layout LyX-Code
 
 from IPython.demo import Demo
 \layout LyX-Code
 
 mydemo = Demo('myscript.py')
 \layout Standard
 
 This creates the 
 \family typewriter 
 mydemo
 \family default 
  object, whose blocks you run one at a time by simply calling the object
  with no arguments.
  If you have autocall active in IPython (the default), all you need to do
  is type
 \layout LyX-Code
 
 mydemo
 \layout Standard
 
 and IPython will call it, executing each block.
  Demo objects can be restarted, you can move forward or back skipping blocks,
  re-execute the last block, etc.
  Simply use the Tab key on a demo object to see its methods, and call 
 \family typewriter 
 `?'
 \family default 
  on them to see their docstrings for more usage details.
  In addition, the 
 \family typewriter 
 demo
 \family default 
  module itself contains a comprehensive docstring, which you can access
  via
 \layout LyX-Code
 
 from IPython import demo
 \layout LyX-Code
 
 demo?
 \layout Standard
 
 
 \series bold 
 Limitations:
 \series default 
  It is important to note that these demos are limited to fairly simple uses.
  In particular, you can 
 \emph on 
 not
 \emph default 
  put division marks in indented code (loops, if statements, function definitions
 , etc.) Supporting something like this would basically require tracking the
  internal execution state of the Python interpreter, so only top-level divisions
  are allowed.
  If you want to be able to open an IPython instance at an arbitrary point
  in a program, you can use IPython's embedding facilities, described in
  detail in Sec\SpecialChar \@.
 \SpecialChar ~
 
 \begin_inset LatexCommand \ref{sec:embed}
 
 \end_inset 
 
 .
 \layout Section
 
 
 \begin_inset LatexCommand \label{sec:matplotlib-support}
 
 \end_inset 
 
 Plotting with 
 \family typewriter 
 matplotlib
 \family default 
  
 \layout Standard
 
 The matplotlib library (
 \begin_inset LatexCommand \htmlurl[http://matplotlib.sourceforge.net]{http://matplotlib.sourceforge.net}
 
 \end_inset 
 
 ) provides high quality 2D plotting for Python.
  Matplotlib can produce plots on screen using a variety of GUI toolkits,
  including Tk, GTK and WXPython.
  It also provides a number of commands useful for scientific computing,
  all with a syntax compatible with that of the popular Matlab program.
 \layout Standard
 
 IPython accepts the special option 
 \family typewriter 
 -pylab
 \family default 
  (Sec.\SpecialChar ~
 
 \begin_inset LatexCommand \ref{sec:cmd-line-opts}
 
 \end_inset 
 
 ).
  This configures it to support matplotlib, honoring the settings in the
  
 \family typewriter 
 .matplotlibrc
 \family default 
  file.
  IPython will detect the user's choice of matplotlib GUI backend, and automatica
 lly select the proper threading model to prevent blocking.
  It also sets matplotlib in interactive mode and modifies 
 \family typewriter 
 %run
 \family default 
  slightly, so that any matplotlib-based script can be executed using 
 \family typewriter 
 %run
 \family default 
  and the final 
 \family typewriter 
 show()
 \family default 
  command does not block the interactive shell.
 \layout Standard
 
 The 
 \family typewriter 
 -pylab
 \family default 
  option must be given first in order for IPython to configure its threading
  mode.
  However, you can still issue other options afterwards.
  This allows you to have a matplotlib-based environment customized with
  additional modules using the standard IPython profile mechanism (Sec.\SpecialChar ~
 
 \begin_inset LatexCommand \ref{sec:profiles}
 
 \end_inset 
 
 ): ``
 \family typewriter 
 ipython -pylab -p myprofile
 \family default 
 '' will load the profile defined in 
 \family typewriter 
 ipythonrc-myprofile
 \family default 
  after configuring matplotlib.
 \layout Section
 
 
 \begin_inset LatexCommand \label{sec:Gnuplot}
 
 \end_inset 
 
 Plotting with 
 \family typewriter 
 Gnuplot
 \layout Standard
 
 Through the magic extension system described in sec.
  
 \begin_inset LatexCommand \ref{sec:magic}
 
 \end_inset 
 
 , IPython incorporates a mechanism for conveniently interfacing with the
  Gnuplot system (
 \begin_inset LatexCommand \htmlurl{http://www.gnuplot.info}
 
 \end_inset 
 
 ).
  Gnuplot is a very complete 2D and 3D plotting package available for many
  operating systems and commonly included in modern Linux distributions.
  
 \layout Standard
 
 Besides having Gnuplot installed, this functionality requires the 
 \family typewriter 
 Gnuplot.py
 \family default 
  module for interfacing python with Gnuplot.
  It can be downloaded from: 
 \begin_inset LatexCommand \htmlurl{http://gnuplot-py.sourceforge.net}
 
 \end_inset 
 
 .
 \layout Subsection
 
 Proper Gnuplot configuration
 \layout Standard
 
 As of version 4.0, Gnuplot has excellent mouse and interactive keyboard support.
  However, as of 
 \family typewriter 
 Gnuplot.py
 \family default 
  version 1.7, a new option was added to communicate between Python and Gnuplot
  via FIFOs (pipes).
  This mechanism, while fast, also breaks the mouse system.
  You must therefore set the variable 
 \family typewriter 
 prefer_fifo_data
 \family default 
  to 
 \family typewriter 
 0
 \family default 
  in file 
 \family typewriter 
 gp_unix.py
 \family default 
  if you wish to keep the interactive mouse and keyboard features working
  properly (
 \family typewriter 
 prefer_inline_data
 \family default 
  also must be 
 \family typewriter 
 0
 \family default 
 , but this is the default so unless you've changed it manually you should
  be fine).
 \layout Standard
 
 'Out of the box', Gnuplot is configured with a rather poor set of size,
  color and linewidth choices which make the graphs fairly hard to read on
  modern high-resolution displays (although they work fine on old 640x480
  ones).
  Below is a section of my 
 \family typewriter 
 .Xdefaults
 \family default 
  file which I use for having a more convenient Gnuplot setup.
  Remember to load it by running 
 \family typewriter 
 `xrdb .Xdefaults`
 \family default 
 :
 \layout Standard
 
 
 \family typewriter 
 !******************************************************************
 \newline 
 ! gnuplot options
 \newline 
 ! modify this for a convenient window size
 \newline 
 gnuplot*geometry: 780x580
 \layout Standard
 
 
 \family typewriter 
 ! on-screen font (not for PostScript)
 \newline 
 gnuplot*font: -misc-fixed-bold-r-normal--15-120-100-100-c-90-iso8859-1
 \layout Standard
 
 
 \family typewriter 
 ! color options
 \newline 
 gnuplot*background: black
 \newline 
 gnuplot*textColor: white
 \newline 
 gnuplot*borderColor: white
 \newline 
 gnuplot*axisColor: white
 \newline 
 gnuplot*line1Color: red
 \newline 
 gnuplot*line2Color: green
 \newline 
 gnuplot*line3Color: blue
 \newline 
 gnuplot*line4Color: magenta
 \newline 
 gnuplot*line5Color: cyan
 \newline 
 gnuplot*line6Color: sienna
 \newline 
 gnuplot*line7Color: orange
 \newline 
 gnuplot*line8Color: coral
 \layout Standard
 
 
 \family typewriter 
 ! multiplicative factor for point styles
 \newline 
 gnuplot*pointsize: 2
 \layout Standard
 
 
 \family typewriter 
 ! line width options (in pixels)
 \newline 
 gnuplot*borderWidth: 2
 \newline 
 gnuplot*axisWidth: 2
 \newline 
 gnuplot*line1Width: 2
 \newline 
 gnuplot*line2Width: 2
 \newline 
 gnuplot*line3Width: 2
 \newline 
 gnuplot*line4Width: 2
 \newline 
 gnuplot*line5Width: 2
 \newline 
 gnuplot*line6Width: 2
 \newline 
 gnuplot*line7Width: 2
 \newline 
 gnuplot*line8Width: 2
 \layout Subsection
 
 The 
 \family typewriter 
 IPython.GnuplotRuntime
 \family default 
  module
 \layout Standard
 
 IPython includes a module called 
 \family typewriter 
 Gnuplot2.py
 \family default 
  which extends and improves the default 
 \family typewriter 
 Gnuplot
 \family default 
 .
 \family typewriter 
 py
 \family default 
  (which it still relies upon).
  For example, the new 
 \family typewriter 
 plot
 \family default 
  function adds several improvements to the original making it more convenient
  for interactive use, and 
 \family typewriter 
 hardcopy
 \family default 
  fixes a bug in the original which under some circumstances blocks the creation
  of PostScript output.
 \layout Standard
 
 For scripting use, 
 \family typewriter 
 GnuplotRuntime.py
 \family default 
  is provided, which wraps 
 \family typewriter 
 Gnuplot2.py
 \family default 
  and creates a series of global aliases.
  These make it easy to control Gnuplot plotting jobs through the Python
  language.
 \layout Standard
 
 Below is some example code which illustrates how to configure Gnuplot inside
  your own programs but have it available for further interactive use through
  an embedded IPython instance.
  Simply run this file at a system prompt.
  This file is provided as 
 \family typewriter 
 example-gnuplot.py
 \family default 
  in the examples directory:
 \layout Standard
 
 
 \begin_inset ERT
 status Open
 
 \layout Standard
 
 \backslash 
 codelist{examples/example-gnuplot.py}
 \end_inset 
 
 
 \layout Subsection
 
 The 
 \family typewriter 
 numeric
 \family default 
  profile: a scientific computing environment
 \layout Standard
 
 The 
 \family typewriter 
 numeric
 \family default 
  IPython profile, which you can activate with 
 \family typewriter 
 `ipython -p numeric
 \family default 
 ' will automatically load the IPython Gnuplot extensions (plus Numeric and
  other useful things for numerical computing), contained in the 
 \family typewriter 
 IPython.GnuplotInteractive
 \family default 
  module.
  This will create the globals 
 \family typewriter 
 Gnuplot 
 \family default 
 (an alias to the improved Gnuplot2 module), 
 \family typewriter 
 gp
 \family default 
  (a Gnuplot active instance), the new magic commands 
 \family typewriter 
 %gpc
 \family default 
  and 
 \family typewriter 
 %gp_set_instance
 \family default 
  and several other convenient globals.
  Type 
 \family typewriter 
 gphelp()
 \family default 
  for further details.
 \layout Standard
 
 This should turn IPython into a convenient environment for numerical computing,
  with all the functions in the NumPy library and the Gnuplot facilities
  for plotting.
  Further improvements can be obtained by loading the SciPy libraries for
  scientific computing, available at 
 \begin_inset LatexCommand \htmlurl{http://scipy.org}
 
 \end_inset 
 
 .
 \layout Standard
 
 If you are in the middle of a working session with numerical objects and
  need to plot them but you didn't start the 
 \family typewriter 
 numeric
 \family default 
  profile, you can load these extensions at any time by typing
 \newline 
 
 \family typewriter 
 from IPython.GnuplotInteractive import *
 \newline 
 
 \family default 
 at the IPython prompt.
  This will allow you to keep your objects intact and start using Gnuplot
  to view them.
 \layout Section
 
 Reporting bugs
 \layout Subsection*
 
 Automatic crash reports
 \layout Standard
 
 Ideally, IPython itself shouldn't crash.
  It will catch exceptions produced by you, but bugs in its internals will
  still crash it.
 \layout Standard
 
 In such a situation, IPython will leave a file named 
 \family typewriter 
 IPython_crash_report.txt
 \family default 
  in your IPYTHONDIR directory (that way if crashes happen several times
  it won't litter many directories, the post-mortem file is always located
  in the same place and new occurrences just overwrite the previous one).
  If you can mail this file to the developers (see sec.
  
 \begin_inset LatexCommand \ref{sec:credits}
 
 \end_inset 
 
  for names and addresses), it will help us 
 \emph on 
 a lot
 \emph default 
  in understanding the cause of the problem and fixing it sooner.
 \layout Subsection*
 
 The bug tracker
 \layout Standard
 
 IPython also has an online bug-tracker, located at 
 \begin_inset LatexCommand \htmlurl{http://projects.scipy.org/ipython/ipython/report/1}
 
 \end_inset 
 
 .
  In addition to mailing the developers, it would be a good idea to file
  a bug report here.
  This will ensure that the issue is properly followed to conclusion.
  To report new bugs you will have to register first.
 \layout Standard
 
 You can also use this bug tracker to file feature requests.
 \layout Section
 
 Brief history
 \layout Subsection
 
 Origins
 \layout Standard
 
 The current IPython system grew out of the following three projects:
 \layout List
 \labelwidthstring 00.00.0000
 
 ipython by Fernando P
 \begin_inset ERT
 status Collapsed
 
 \layout Standard
 
 \backslash 
 '{e}
 \end_inset 
 
 rez.
  I was working on adding Mathematica-type prompts and a flexible configuration
  system (something better than 
 \family typewriter 
 $PYTHONSTARTUP
 \family default 
 ) to the standard Python interactive interpreter.
 \layout List
 \labelwidthstring 00.00.0000
 
 IPP by Janko Hauser.
  Very well organized, great usability.
  Had an old help system.
  IPP was used as the `container' code into which I added the functionality
  from ipython and LazyPython.
 \layout List
 \labelwidthstring 00.00.0000
 
 LazyPython by Nathan Gray.
  Simple but 
 \emph on 
 very
 \emph default 
  powerful.
  The quick syntax (auto parens, auto quotes) and verbose/colored tracebacks
  were all taken from here.
 \layout Standard
 
 When I found out (see sec.
  
 \begin_inset LatexCommand \ref{figgins}
 
 \end_inset 
 
 ) about IPP and LazyPython I tried to join all three into a unified system.
  I thought this could provide a very nice working environment, both for
  regular programming and scientific computing: shell-like features, IDL/Matlab
  numerics, Mathematica-type prompt history and great object introspection
  and help facilities.
  I think it worked reasonably well, though it was a lot more work than I
  had initially planned.
 \layout Subsection
 
 Current status
 \layout Standard
 
 The above listed features work, and quite well for the most part.
  But until a major internal restructuring is done (see below), only bug
  fixing will be done, no other features will be added (unless very minor
  and well localized in the cleaner parts of the code).
 \layout Standard
 
 IPython consists of some 18000 lines of pure python code, of which roughly
  two thirds is reasonably clean.
  The rest is, messy code which needs a massive restructuring before any
  further major work is done.
  Even the messy code is fairly well documented though, and most of the problems
  in the (non-existent) class design are well pointed to by a PyChecker run.
  So the rewriting work isn't that bad, it will just be time-consuming.
 \layout Subsection
 
 Future
 \layout Standard
 
 See the separate 
 \family typewriter 
 new_design
 \family default 
  document for details.
  Ultimately, I would like to see IPython become part of the standard Python
  distribution as a `big brother with batteries' to the standard Python interacti
 ve interpreter.
  But that will never happen with the current state of the code, so all contribut
 ions are welcome.
 \layout Section
 
 License
 \layout Standard
 
 IPython is released under the terms of the BSD license, whose general form
  can be found at: 
 \begin_inset LatexCommand \htmlurl{http://www.opensource.org/licenses/bsd-license.php}
 
 \end_inset 
 
 .
  The full text of the IPython license is reproduced below:
 \layout Quote
 
 
 \family typewriter 
 \size small 
 IPython is released under a BSD-type license.
 \layout Quote
 
 
 \family typewriter 
 \size small 
 Copyright (c) 2001, 2002, 2003, 2004 Fernando Perez <[e-mail]>.
 \layout Quote
 
 
 \family typewriter 
 \size small 
 Copyright (c) 2001 Janko Hauser <[e-mail]> and 
 \newline 
 Nathaniel Gray <[e-mail]>.
 \layout Quote
 
 
 \family typewriter 
 \size small 
 All rights reserved.
 \layout Quote
 
 
 \family typewriter 
 \size small 
 Redistribution and use in source and binary forms, with or without modification,
  are permitted provided that the following conditions are met:
 \layout Quote
 
 
 \family typewriter 
 \size small 
 a.
  Redistributions of source code must retain the above copyright notice,
  this list of conditions and the following disclaimer.
 \layout Quote
 
 
 \family typewriter 
 \size small 
 b.
  Redistributions in binary form must reproduce the above copyright notice,
  this list of conditions and the following disclaimer in the documentation
  and/or other materials provided with the distribution.
 \layout Quote
 
 
 \family typewriter 
 \size small 
 c.
  Neither the name of the copyright holders nor the names of any contributors
  to this software may be used to endorse or promote products derived from
  this software without specific prior written permission.
 \layout Quote
 
 
 \family typewriter 
 \size small 
 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
  IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
  THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  PURPOSE ARE DISCLAIMED.
  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
  INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
  BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
  USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
  ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  
 \layout Standard
 
 Individual authors are the holders of the copyright for their code and are
  listed in each file.
 \layout Standard
 
 Some files (
 \family typewriter 
 DPyGetOpt.py
 \family default 
 , for example) may be licensed under different conditions.
  Ultimately each file indicates clearly the conditions under which its author/au
 thors have decided to publish the code.
 \layout Standard
 
 Versions of IPython up to and including 0.6.3 were released under the GNU
  Lesser General Public License (LGPL), available at 
 \begin_inset LatexCommand \htmlurl{http://www.gnu.org/copyleft/lesser.html}
 
 \end_inset 
 
 .
 \layout Section
 
 
 \begin_inset LatexCommand \label{sec:credits}
 
 \end_inset 
 
 Credits
 \layout Standard
 
 IPython is mainly developed by Fernando P
 \begin_inset ERT
 status Collapsed
 
 \layout Standard
 
 \backslash 
 '{e}
 \end_inset 
 
 rez 
 \family typewriter 
 <[e-mail]>
 \family default 
 , but the project was born from mixing in Fernando's code with the IPP project
  by Janko Hauser 
 \family typewriter 
 <jhauser-AT-zscout.de>
 \family default 
  and LazyPython by Nathan Gray 
 \family typewriter 
 <n8gray-AT-caltech.edu>
 \family default 
 .
  For all IPython-related requests, please contact Fernando.
  
 \layout Standard
 
 As of early 2006, the following developers have joined the core team:
 \layout List
 \labelwidthstring 00.00.0000
 
 Robert\SpecialChar ~
 Kern 
 \family typewriter 
 <rkern-AT-enthought.com>
 \family default 
 : co-mentored the 2005 Google Summer of Code project to develop python interacti
 ve notebooks (XML documents) and graphical interface.
  This project was awarded to the students Tzanko Matev 
 \family typewriter 
 <tsanko-AT-gmail.com>
 \family default 
  and Toni Alatalo 
 \family typewriter 
 <antont-AT-an.org>
 \layout List
 \labelwidthstring 00.00.0000
 
 Brian\SpecialChar ~
 Granger 
 \family typewriter 
 <bgranger-AT-scu.edu>
 \family default 
 : extending IPython to allow support for interactive parallel computing.
 \layout List
 \labelwidthstring 00.00.0000
 
 Ville\SpecialChar ~
 Vainio 
 \family typewriter 
 <vivainio-AT-gmail.com>
 \family default 
 : Ville is the new maintainer for the main trunk of IPython after version
  0.7.1.
 \layout Standard
 
 User or development help should be requested via the IPython mailing lists:
 \layout Description
 
 User\SpecialChar ~
 list: 
 \begin_inset LatexCommand \htmlurl{http://scipy.net/mailman/listinfo/ipython-user}
 
 \end_inset 
 
 
 \layout Description
 
 Developer's\SpecialChar ~
 list: 
 \begin_inset LatexCommand \htmlurl{http://scipy.net/mailman/listinfo/ipython-dev}
 
 \end_inset 
 
 
 \layout Standard
 
 The IPython project is also very grateful to
 \begin_inset Foot
 collapsed true
 
 \layout Standard
 
 I've mangled email addresses to reduce spam, since the IPython manuals can
  be accessed online.
 \end_inset 
 
 :
 \layout Standard
 
 Bill Bumgarner 
 \family typewriter 
 <bbum-AT-friday.com>
 \family default 
 : for providing the DPyGetOpt module which gives very powerful and convenient
  handling of command-line options (light years ahead of what Python 2.1.1's
  getopt module does).
 \layout Standard
 
 Ka-Ping Yee 
 \family typewriter 
 <ping-AT-lfw.org>
 \family default 
 : for providing the Itpl module for convenient and powerful string interpolation
  with a much nicer syntax than formatting through the '%' operator.
 \layout Standard
 
 Arnd Baecker 
 \family typewriter 
 <baecker-AT-physik.tu-dresden.de>
 \family default 
 : for his many very useful suggestions and comments, and lots of help with
  testing and documentation checking.
  Many of IPython's newer features are a result of discussions with him (bugs
  are still my fault, not his).
 \layout Standard
 
 Obviously Guido van\SpecialChar ~
 Rossum and the whole Python development team, that goes
  without saying.
 \layout Standard
 
 IPython's website is generously hosted at 
 \begin_inset LatexCommand \htmlurl{http://ipython.scipy.org}
 
 \end_inset 
 
  by Enthought (
 \begin_inset LatexCommand \htmlurl{http://www.enthought.com}
 
 \end_inset 
 
 ).
  I am very grateful to them and all of the SciPy team for their contribution.
 \layout Standard
 
 
 \begin_inset LatexCommand \label{figgins}
 
 \end_inset 
 
 Fernando would also like to thank Stephen Figgins 
 \family typewriter 
 <fig-AT-monitor.net>
 \family default 
 , an O'Reilly Python editor.
  His Oct/11/2001 article about IPP and LazyPython, was what got this project
  started.
  You can read it at: 
 \begin_inset LatexCommand \htmlurl{http://www.onlamp.com/pub/a/python/2001/10/11/pythonnews.html}
 
 \end_inset 
 
 .
 \layout Standard
 
 And last but not least, all the kind IPython users who have emailed new
  code, bug reports, fixes, comments and ideas.
  A brief list follows, please let me know if I have ommitted your name by
  accident: 
 \layout List
 \labelwidthstring 00.00.0000
 
 Jack\SpecialChar ~
 Moffit 
 \family typewriter 
 <jack-AT-xiph.org>
 \family default 
  Bug fixes, including the infamous color problem.
  This bug alone caused many lost hours and frustration, many thanks to him
  for the fix.
  I've always been a fan of Ogg & friends, now I have one more reason to
  like these folks.
 \newline 
 Jack is also contributing with Debian packaging and many other things.
 \layout List
 \labelwidthstring 00.00.0000
 
 Alexander\SpecialChar ~
 Schmolck 
 \family typewriter 
 <a.schmolck-AT-gmx.net> 
 \family default 
 Emacs work, bug reports, bug fixes, ideas, lots more.
  The ipython.el mode for (X)Emacs is Alex's code, providing full support
  for IPython under (X)Emacs.
 \layout List
 \labelwidthstring 00.00.0000
 
 Andrea\SpecialChar ~
 Riciputi 
 \family typewriter 
 <andrea.riciputi-AT-libero.it>
 \family default 
  Mac OSX information, Fink package management.
 \layout List
 \labelwidthstring 00.00.0000
 
 Gary\SpecialChar ~
 Bishop 
 \family typewriter 
 <gb-AT-cs.unc.edu>
 \family default 
  Bug reports, and patches to work around the exception handling idiosyncracies
  of WxPython.
  Readline and color support for Windows.
 \layout List
 \labelwidthstring 00.00.0000
 
 Jeffrey\SpecialChar ~
 Collins 
 \family typewriter 
 <Jeff.Collins-AT-vexcel.com>
 \family default 
  Bug reports.
  Much improved readline support, including fixes for Python 2.3.
 \layout List
 \labelwidthstring 00.00.0000
 
 Dryice\SpecialChar ~
 Liu 
 \family typewriter 
 <dryice-AT-liu.com.cn>
 \family default 
  FreeBSD port.
 \layout List
 \labelwidthstring 00.00.0000
 
 Mike\SpecialChar ~
 Heeter 
 \family typewriter 
 <korora-AT-SDF.LONESTAR.ORG>
 \layout List
 \labelwidthstring 00.00.0000
 
 Christopher\SpecialChar ~
 Hart 
 \family typewriter 
 <hart-AT-caltech.edu>
 \family default 
  PDB integration.
 \layout List
 \labelwidthstring 00.00.0000
 
 Milan\SpecialChar ~
 Zamazal 
 \family typewriter 
 <pdm-AT-zamazal.org>
 \family default 
  Emacs info.
 \layout List
 \labelwidthstring 00.00.0000
 
 Philip\SpecialChar ~
 Hisley 
 \family typewriter 
 <compsys-AT-starpower.net>
 \layout List
 \labelwidthstring 00.00.0000
 
 Holger\SpecialChar ~
 Krekel 
 \family typewriter 
 <pyth-AT-devel.trillke.net>
 \family default 
  Tab completion, lots more.
 \layout List
 \labelwidthstring 00.00.0000
 
 Robin\SpecialChar ~
 Siebler 
 \family typewriter 
 <robinsiebler-AT-starband.net>
 \layout List
 \labelwidthstring 00.00.0000
 
 Ralf\SpecialChar ~
 Ahlbrink
 \family typewriter 
  <ralf_ahlbrink-AT-web.de>
 \layout List
 \labelwidthstring 00.00.0000
 
 Thorsten\SpecialChar ~
 Kampe 
 \family typewriter 
 <thorsten-AT-thorstenkampe.de>
 \layout List
 \labelwidthstring 00.00.0000
 
 Fredrik\SpecialChar ~
 Kant 
 \family typewriter 
 <fredrik.kant-AT-front.com>
 \family default 
  Windows setup.
 \layout List
 \labelwidthstring 00.00.0000
 
 Syver\SpecialChar ~
 Enstad 
 \family typewriter 
 <syver-en-AT-online.no>
 \family default 
  Windows setup.
 \layout List
 \labelwidthstring 00.00.0000
 
 Richard 
 \family typewriter 
 <rxe-AT-renre-europe.com>
 \family default 
  Global embedding.
 \layout List
 \labelwidthstring 00.00.0000
 
 Hayden\SpecialChar ~
 Callow 
 \family typewriter 
 <h.callow-AT-elec.canterbury.ac.nz>
 \family default 
  Gnuplot.py 1.6 compatibility.
 \layout List
 \labelwidthstring 00.00.0000
 
 Leonardo\SpecialChar ~
 Santagada 
 \family typewriter 
 <retype-AT-terra.com.br>
 \family default 
  Fixes for Windows installation.
 \layout List
 \labelwidthstring 00.00.0000
 
 Christopher\SpecialChar ~
 Armstrong 
 \family typewriter 
 <radix-AT-twistedmatrix.com>
 \family default 
  Bugfixes.
 \layout List
 \labelwidthstring 00.00.0000
 
 Francois\SpecialChar ~
 Pinard 
 \family typewriter 
 <pinard-AT-iro.umontreal.ca>
 \family default 
  Code and documentation fixes.
 \layout List
 \labelwidthstring 00.00.0000
 
 Cory\SpecialChar ~
 Dodt 
 \family typewriter 
 <cdodt-AT-fcoe.k12.ca.us>
 \family default 
  Bug reports and Windows ideas.
  Patches for Windows installer.
 \layout List
 \labelwidthstring 00.00.0000
 
 Olivier\SpecialChar ~
 Aubert 
 \family typewriter 
 <oaubert-AT-bat710.univ-lyon1.fr>
 \family default 
  New magics.
 \layout List
 \labelwidthstring 00.00.0000
 
 King\SpecialChar ~
 C.\SpecialChar ~
 Shu 
 \family typewriter 
 <kingshu-AT-myrealbox.com>
 \family default 
  Autoindent patch.
 \layout List
 \labelwidthstring 00.00.0000
 
 Chris\SpecialChar ~
 Drexler 
 \family typewriter 
 <chris-AT-ac-drexler.de>
 \family default 
  Readline packages for Win32/CygWin.
 \layout List
 \labelwidthstring 00.00.0000
 
 Gustavo\SpecialChar ~
 Cordova\SpecialChar ~
 Avila 
 \family typewriter 
 <gcordova-AT-sismex.com>
 \family default 
  EvalDict code for nice, lightweight string interpolation.
 \layout List
 \labelwidthstring 00.00.0000
 
 Kasper\SpecialChar ~
 Souren 
 \family typewriter 
 <Kasper.Souren-AT-ircam.fr>
 \family default 
  Bug reports, ideas.
 \layout List
 \labelwidthstring 00.00.0000
 
 Gever\SpecialChar ~
 Tulley 
 \family typewriter 
 <gever-AT-helium.com>
 \family default 
  Code contributions.
 \layout List
 \labelwidthstring 00.00.0000
 
 Ralf\SpecialChar ~
 Schmitt 
 \family typewriter 
 <ralf-AT-brainbot.com>
 \family default 
  Bug reports & fixes.
 \layout List
 \labelwidthstring 00.00.0000
 
 Oliver\SpecialChar ~
 Sander 
 \family typewriter 
 <osander-AT-gmx.de>
 \family default 
  Bug reports.
 \layout List
 \labelwidthstring 00.00.0000
 
 Rod\SpecialChar ~
 Holland 
 \family typewriter 
 <rhh-AT-structurelabs.com>
 \family default 
  Bug reports and fixes to logging module.
 \layout List
 \labelwidthstring 00.00.0000
 
 Daniel\SpecialChar ~
 'Dang'\SpecialChar ~
 Griffith 
 \family typewriter 
 <pythondev-dang-AT-lazytwinacres.net>
 \family default 
  Fixes, enhancement suggestions for system shell use.
 \layout List
 \labelwidthstring 00.00.0000
 
 Viktor\SpecialChar ~
 Ransmayr 
 \family typewriter 
 <viktor.ransmayr-AT-t-online.de>
 \family default 
  Tests and reports on Windows installation issues.
  Contributed a true Windows binary installer.
 \layout List
 \labelwidthstring 00.00.0000
 
 Mike\SpecialChar ~
 Salib 
 \family typewriter 
 <msalib-AT-mit.edu>
 \family default 
  Help fixing a subtle bug related to traceback printing.
 \layout List
 \labelwidthstring 00.00.0000
 
 W.J.\SpecialChar ~
 van\SpecialChar ~
 der\SpecialChar ~
 Laan 
 \family typewriter 
 <gnufnork-AT-hetdigitalegat.nl>
 \family default 
  Bash-like prompt specials.
 \layout List
 \labelwidthstring 00.00.0000
 
 Antoon\SpecialChar ~
 Pardon 
 \family typewriter 
 <Antoon.Pardon-AT-rece.vub.ac.be>
 \family default 
  Critical fix for the multithreaded IPython.
 \layout List
 \labelwidthstring 00.00.0000
 
 John\SpecialChar ~
 Hunter 
 \family typewriter 
 <jdhunter-AT-nitace.bsd.uchicago.edu>
 \family default 
  Matplotlib author, helped with all the development of support for matplotlib
  in IPyhton, including making necessary changes to matplotlib itself.
 \layout List
 \labelwidthstring 00.00.0000
 
 Matthew\SpecialChar ~
 Arnison 
 \family typewriter 
 <maffew-AT-cat.org.au>
 \family default 
  Bug reports, `
 \family typewriter 
 %run -d
 \family default 
 ' idea.
 \layout List
 \labelwidthstring 00.00.0000
 
 Prabhu\SpecialChar ~
 Ramachandran 
 \family typewriter 
 <prabhu_r-AT-users.sourceforge.net>
 \family default 
  Help with (X)Emacs support, threading patches, ideas...
 \layout List
 \labelwidthstring 00.00.0000
 
 Norbert\SpecialChar ~
 Tretkowski 
 \family typewriter 
 <tretkowski-AT-inittab.de>
 \family default 
  help with Debian packaging and distribution.
 \layout List
 \labelwidthstring 00.00.0000
 
 George\SpecialChar ~
 Sakkis <
 \family typewriter 
 gsakkis-AT-eden.rutgers.edu>
 \family default 
  New matcher for tab-completing named arguments of user-defined functions.
 \layout List
 \labelwidthstring 00.00.0000
 
 J�rgen\SpecialChar ~
 Stenarson 
 \family typewriter 
 <jorgen.stenarson-AT-bostream.nu>
 \family default 
  Wildcard support implementation for searching namespaces.
 \layout List
 \labelwidthstring 00.00.0000
 
 Vivian\SpecialChar ~
 De\SpecialChar ~
 Smedt 
 \family typewriter 
 <vivian-AT-vdesmedt.com>
 \family default 
  Debugger enhancements, so that when pdb is activated from within IPython,
  coloring, tab completion and other features continue to work seamlessly.
 \layout List
 \labelwidthstring 00.00.0000
 
 Scott\SpecialChar ~
 Tsai 
 \family typewriter 
 <scottt958-AT-yahoo.com.tw>
 \family default 
  Support for automatic editor invocation on syntax errors (see 
 \begin_inset LatexCommand \htmlurl{http://www.scipy.net/roundup/ipython/issue36}
 
 \end_inset 
 
 ).
 \layout List
 \labelwidthstring 00.00.0000
 
 Alexander\SpecialChar ~
 Belchenko 
 \family typewriter 
 <bialix-AT-ukr.net>
 \family default 
  Improvements for win32 paging system.
 \layout List
 \labelwidthstring 00.00.0000
 
 Will\SpecialChar ~
 Maier 
 \family typewriter 
 <willmaier-AT-ml1.net>
 \family default 
  Official OpenBSD port.
 \the_end