Shell.py => core/shell.py and imports updated.

IPython/__init__.py

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

IPython/core/ipapi.py

@@ -1,685 +1,685 b''
 """IPython customization API
 
 Your one-stop module for configuring & extending ipython
 
 The API will probably break when ipython 1.0 is released, but so 
 will the other configuration method (rc files).
 
 All names prefixed by underscores are for internal use, not part 
 of the public api.
 
 Below is an example that you can just put to a module and import from ipython. 
 
 A good practice is to install the config script below as e.g. 
 
 ~/.ipython/my_private_conf.py
 
 And do 
 
 import_mod my_private_conf 
 
 in ~/.ipython/ipythonrc
 
 That way the module is imported at startup and you can have all your
 personal configuration (as opposed to boilerplate ipythonrc-PROFILENAME 
 stuff) in there. 
 
 from IPython.core import ipapi
 ip = ipapi.get()
 
 def ankka_f(self, arg):
     print 'Ankka',self,'says uppercase:',arg.upper()
 
 ip.expose_magic('ankka',ankka_f)
 
 ip.magic('alias sayhi echo "Testing, hi ok"')
 ip.magic('alias helloworld echo "Hello world"')
 ip.system('pwd')
 
 ip.ex('import re')
 ip.ex('''
 def funcci(a,b):
     print a+b
 print funcci(3,4)
 ''')
 ip.ex('funcci(348,9)')
 
 def jed_editor(self,filename, linenum=None):
     print 'Calling my own editor, jed ... via hook!'
     import os
     if linenum is None: linenum = 0
     os.system('jed +%d %s' % (linenum, filename))
     print 'exiting jed'
 
 ip.set_hook('editor',jed_editor)
 
 o = ip.options
 o.autocall = 2  # FULL autocall mode
 
 print 'done!'
 """
 
 #-----------------------------------------------------------------------------
 # Modules and globals
 
 # stdlib imports
 import __builtin__
 import sys
 
 # contains the most recently instantiated IPApi
 _RECENT_IP = None
 
 #-----------------------------------------------------------------------------
 # Code begins
 
 class TryNext(Exception):
     """Try next hook exception.
      
     Raise this in your hook function to indicate that the next hook handler
     should be used to handle the operation.  If you pass arguments to the
     constructor those arguments will be used by the next hook instead of the
     original ones.
     """
 
     def __init__(self, *args, **kwargs):
         self.args = args
         self.kwargs = kwargs
 
 
 class UsageError(Exception):
     """ Error in magic function arguments, etc.
     
     Something that probably won't warrant a full traceback, but should
     nevertheless interrupt a macro / batch file.   
     """
 
 
 class IPyAutocall:
     """ Instances of this class are always autocalled
     
     This happens regardless of 'autocall' variable state. Use this to
     develop macro-like mechanisms.
     """
     
     def set_ip(self,ip):
         """ Will be used to set _ip point to current ipython instance b/f call
         
         Override this method if you don't want this to happen.
         
         """
         self._ip = ip
     
 
 class IPythonNotRunning:
     """Dummy do-nothing class.
 
     Instances of this class return a dummy attribute on all accesses, which
     can be called and warns.  This makes it easier to write scripts which use
     the ipapi.get() object for informational purposes to operate both with and
     without ipython.  Obviously code which uses the ipython object for
     computations will not work, but this allows a wider range of code to
     transparently work whether ipython is being used or not."""
 
     def __init__(self,warn=True):
         if warn:
             self.dummy = self._dummy_warn
         else:
             self.dummy = self._dummy_silent
     
     def __str__(self):
         return "<IPythonNotRunning>"
 
     __repr__ = __str__
 
     def __getattr__(self,name):
         return self.dummy
 
     def _dummy_warn(self,*args,**kw):
         """Dummy function, which doesn't do anything but warn."""
 
         print ("IPython is not running, this is a dummy no-op function")
 
     def _dummy_silent(self,*args,**kw):
         """Dummy function, which doesn't do anything and emits no warnings."""
         pass
 
 
 def get(allow_dummy=False,dummy_warn=True):
     """Get an IPApi object.
 
     If allow_dummy is true, returns an instance of IPythonNotRunning 
     instead of None if not running under IPython.
 
     If dummy_warn is false, the dummy instance will be completely silent.
 
     Running this should be the first thing you do when writing extensions that
     can be imported as normal modules. You can then direct all the
     configuration operations against the returned object.
     """
     global _RECENT_IP
     if allow_dummy and not _RECENT_IP:
         _RECENT_IP = IPythonNotRunning(dummy_warn)
     return _RECENT_IP
 
 
 class IPApi(object):
     """ The actual API class for configuring IPython 
     
     You should do all of the IPython configuration by getting an IPApi object
     with IPython.ipapi.get() and using the attributes and methods of the
     returned object."""
     
     def __init__(self,ip):
         
         global _RECENT_IP
 
         # All attributes exposed here are considered to be the public API of
         # IPython.  As needs dictate, some of these may be wrapped as
         # properties.
 
         self.magic = ip.ipmagic
         
         self.system = ip.system
         
         self.set_hook = ip.set_hook
         
         self.set_custom_exc = ip.set_custom_exc
 
         self.user_ns = ip.user_ns
 
         self.set_crash_handler = ip.set_crash_handler
 
         # Session-specific data store, which can be used to store
         # data that should persist through the ipython session.
         self.meta =  ip.meta
     
         # The ipython instance provided
         self.IP = ip
 
         self.extensions = {}
 
         self.dbg = DebugTools(self)
         
         _RECENT_IP = self
 
     # Use a property for some things which are added to the instance very
     # late.  I don't have time right now to disentangle the initialization
     # order issues, so a property lets us delay item extraction while
     # providing a normal attribute API.
     def get_db(self):
         """A handle to persistent dict-like database (a PickleShareDB object)"""
         return self.IP.db
 
     db = property(get_db,None,None,get_db.__doc__)
 
     def get_options(self):
         """All configurable variables."""
         
         # catch typos by disabling new attribute creation. If new attr creation
         # is in fact wanted (e.g. when exposing new options), do
         # allow_new_attr(True) for the received rc struct.
         
         self.IP.rc.allow_new_attr(False)
         return self.IP.rc
 
     options = property(get_options,None,None,get_options.__doc__)
     
     def expose_magic(self,magicname, func):
         """Expose own function as magic function for ipython 
     
         def foo_impl(self,parameter_s=''):
             'My very own magic!. (Use docstrings, IPython reads them).'
             print 'Magic function. Passed parameter is between < >:'
             print '<%s>' % parameter_s
             print 'The self object is:',self
     
         ipapi.expose_magic('foo',foo_impl)
         """
         
         import new
         im = new.instancemethod(func,self.IP, self.IP.__class__)
         old = getattr(self.IP, "magic_" + magicname, None)
         if old:
             self.dbg.debug_stack("Magic redefinition '%s', old %s" %
                                  (magicname,old) )
             
         setattr(self.IP, "magic_" + magicname, im)
     
     def ex(self,cmd):
         """ Execute a normal python statement in user namespace """
         exec cmd in self.user_ns
     
     def ev(self,expr):
         """ Evaluate python expression expr in user namespace 
         
         Returns the result of evaluation"""
         return eval(expr,self.user_ns)
     
     def runlines(self,lines):
         """ Run the specified lines in interpreter, honoring ipython directives.
         
         This allows %magic and !shell escape notations.
         
         Takes either all lines in one string or list of lines.
         """
 
         def cleanup_ipy_script(script):
             """ Make a script safe for _ip.runlines() 
             
             - Removes empty lines Suffixes all indented blocks that end with
             - unindented lines with empty lines
             """
             
             res = []
             lines = script.splitlines()
 
             level = 0
             for l in lines:
                 lstripped = l.lstrip()
                 stripped = l.strip()                
                 if not stripped:
                     continue
                 newlevel = len(l) - len(lstripped)
                 def is_secondary_block_start(s):
                     if not s.endswith(':'):
                         return False
                     if (s.startswith('elif') or 
                         s.startswith('else') or 
                         s.startswith('except') or
                         s.startswith('finally')):
                         return True
                         
                 if level > 0 and newlevel == 0 and \
                        not is_secondary_block_start(stripped): 
                     # add empty line
                     res.append('')
                     
                 res.append(l)
                 level = newlevel
             return '\n'.join(res) + '\n'
         
         if isinstance(lines,basestring):
             script = lines            
         else:
             script = '\n'.join(lines)
         clean=cleanup_ipy_script(script)
         # print "_ip.runlines() script:\n",clean # dbg
         self.IP.runlines(clean)
         
     def to_user_ns(self,vars, interactive = True):
         """Inject a group of variables into the IPython user namespace.
 
         Inputs:
 
          - vars: string with variable names separated by whitespace, or a
          dict with name/value pairs.
 
          - interactive: if True (default), the var will be listed with
         %whos et. al.
          
         This utility routine is meant to ease interactive debugging work,
         where you want to easily propagate some internal variable in your code
         up to the interactive namespace for further exploration.
 
         When you run code via %run, globals in your script become visible at
         the interactive prompt, but this doesn't happen for locals inside your
         own functions and methods.  Yet when debugging, it is common to want
         to explore some internal variables further at the interactive propmt.
 
         Examples:
 
         To use this, you first must obtain a handle on the ipython object as
         indicated above, via:
 
         from IPython.core import ipapi
         ip = ipapi.get()
 
         Once this is done, inside a routine foo() where you want to expose
         variables x and y, you do the following:
 
         def foo():
             ...
             x = your_computation()
             y = something_else()
             
             # This pushes x and y to the interactive prompt immediately, even
             # if this routine crashes on the next line after:
             ip.to_user_ns('x y')
             ...
             
             # To expose *ALL* the local variables from the function, use:
             ip.to_user_ns(locals())
 
             ...
             # return           
         
 
         If you need to rename variables, the dict input makes it easy.  For
         example, this call exposes variables 'foo' as 'x' and 'bar' as 'y'
         in IPython user namespace:
 
         ip.to_user_ns(dict(x=foo,y=bar))    
         """
 
         # print 'vars given:',vars # dbg
         
         # We need a dict of name/value pairs to do namespace updates.
         if isinstance(vars,dict):
             # If a dict was given, no need to change anything.
             vdict = vars
         elif isinstance(vars,basestring):
             # If a string with names was given, get the caller's frame to
             # evaluate the given names in
             cf = sys._getframe(1)
             vdict = {}
             for name in vars.split():
                 try:
                     vdict[name] = eval(name,cf.f_globals,cf.f_locals)
                 except:
                     print ('could not get var. %s from %s' %
                     (name,cf.f_code.co_name))
         else:
             raise ValueError('vars must be a string or a dict')
             
         # Propagate variables to user namespace
         self.user_ns.update(vdict)
 
         # And configure interactive visibility
         config_ns = self.IP.user_config_ns
         if interactive:
             for name,val in vdict.iteritems():
                 config_ns.pop(name,None)
         else:
             for name,val in vdict.iteritems():
                 config_ns[name] = val                    
 
     def expand_alias(self,line):
         """ Expand an alias in the command line 
         
         Returns the provided command line, possibly with the first word 
         (command) translated according to alias expansion rules.
         
         [ipython]|16> _ip.expand_aliases("np myfile.txt")
                  <16> 'q:/opt/np/notepad++.exe myfile.txt'
         """
         
         pre,fn,rest = self.IP.split_user_input(line)
         res = pre + self.IP.expand_aliases(fn,rest)
         return res
 
     def itpl(self, s, depth = 1):
         """ Expand Itpl format string s.
         
         Only callable from command line (i.e. prefilter results);
         If you use in your scripts, you need to use a bigger depth!
         """
         return self.IP.var_expand(s, depth)
         
     def defalias(self, name, cmd):
         """ Define a new alias
         
         _ip.defalias('bb','bldmake bldfiles')
         
         Creates a new alias named 'bb' in ipython user namespace
         """
 
         self.dbg.check_hotname(name)
         
         if name in self.IP.alias_table:
             self.dbg.debug_stack("Alias redefinition: '%s' => '%s' (old '%s')"
                                  % (name, cmd, self.IP.alias_table[name]))
 
         if callable(cmd):
             self.IP.alias_table[name] = cmd
             from IPython.core import shadowns
             setattr(shadowns, name,cmd)
             return
             
         if isinstance(cmd,basestring):
             nargs = cmd.count('%s')
             if nargs>0 and cmd.find('%l')>=0:
                 raise Exception('The %s and %l specifiers are mutually '
                                 'exclusive in alias definitions.')
                   
             self.IP.alias_table[name] = (nargs,cmd)
             return
         
         # just put it in - it's probably (0,'foo')
         self.IP.alias_table[name] = cmd
     
     def defmacro(self, *args):
         """ Define a new macro
     
         2 forms of calling:
         
         mac = _ip.defmacro('print "hello"\nprint "world"')
         
         (doesn't put the created macro on user namespace)
         
         _ip.defmacro('build', 'bldmake bldfiles\nabld build winscw udeb')
         
         (creates a macro named 'build' in user namespace)
         """
         
         from IPython.core import macro
         
         if len(args) == 1:
             return macro.Macro(args[0])
         elif len(args) == 2:
             self.user_ns[args[0]] = macro.Macro(args[1])
         else:
             return Exception("_ip.defmacro must be called with 1 or 2 arguments")
         
     def set_next_input(self, s):
         """ Sets the 'default' input string for the next command line.
         
         Requires readline.
         
         Example:
         
         [D:\ipython]|1> _ip.set_next_input("Hello Word")
         [D:\ipython]|2> Hello Word_  # cursor is here        
         """
 
         self.IP.rl_next_input = s
 
     def load(self, mod):
         """ Load an extension.
         
         Some modules should (or must) be 'load()':ed, rather than just imported.
         
         Loading will do:
         
         - run init_ipython(ip)
         - run ipython_firstrun(ip)
         """
         
         if mod in self.extensions:
             # just to make sure we don't init it twice
             # note that if you 'load' a module that has already been
             # imported, init_ipython gets run anyway
             
             return self.extensions[mod]
         __import__(mod)
         m = sys.modules[mod]
         if hasattr(m,'init_ipython'):
             m.init_ipython(self)
             
         if hasattr(m,'ipython_firstrun'):
             already_loaded = self.db.get('firstrun_done', set())
             if mod not in already_loaded:
                 m.ipython_firstrun(self)
                 already_loaded.add(mod)
                 self.db['firstrun_done'] = already_loaded
             
         self.extensions[mod] = m
         return m
 
 
 class DebugTools:
     """ Used for debugging mishaps in api usage
     
     So far, tracing redefinitions is supported.
     """
     
     def __init__(self, ip):
         self.ip = ip
         self.debugmode = False
         self.hotnames = set()
         
     def hotname(self, name_to_catch):
         self.hotnames.add(name_to_catch)
         
     def debug_stack(self, msg = None):
         if not self.debugmode:
             return
         
         import traceback
         if msg is not None:
             print '====== %s  ========' % msg
         traceback.print_stack()
 
     def check_hotname(self,name):
         if name in self.hotnames:
             self.debug_stack( "HotName '%s' caught" % name)
 
 
 def launch_new_instance(user_ns = None,shellclass = None):
     """ Make and start a new ipython instance.
     
     This can be called even without having an already initialized 
     ipython session running.
     
     This is also used as the egg entry point for the 'ipython' script.
     
     """
     ses = make_session(user_ns,shellclass)
     ses.mainloop()
 
 
 def make_user_ns(user_ns = None):
     """Return a valid user interactive namespace.
 
     This builds a dict with the minimal information needed to operate as a
     valid IPython user namespace, which you can pass to the various embedding
     classes in ipython.
 
     This API is currently deprecated. Use ipapi.make_user_namespaces() instead
     to make both the local and global namespace objects simultaneously.
 
     :Parameters:
         user_ns : dict-like, optional
             The current user namespace. The items in this namespace should be
             included in the output. If None, an appropriate blank namespace
             should be created.
 
     :Returns:
         A dictionary-like object to be used as the local namespace of the
         interpreter.
     """
 
     raise NotImplementedError
 
 
 def make_user_global_ns(ns = None):
     """Return a valid user global namespace.
 
     Similar to make_user_ns(), but global namespaces are really only needed in
     embedded applications, where there is a distinction between the user's
     interactive namespace and the global one where ipython is running.
 
     This API is currently deprecated. Use ipapi.make_user_namespaces() instead
     to make both the local and global namespace objects simultaneously.
 
     :Parameters:
         ns : dict, optional
             The current user global namespace. The items in this namespace
             should be included in the output. If None, an appropriate blank
             namespace should be created.
 
     :Returns:
         A true dict to be used as the global namespace of the interpreter.
     """
 
     raise NotImplementedError
 
 # Record the true objects in order to be able to test if the user has overridden
 # these API functions.
 _make_user_ns = make_user_ns
 _make_user_global_ns = make_user_global_ns
 
 
 def make_user_namespaces(user_ns = None,user_global_ns = None):
     """Return a valid local and global user interactive namespaces.
 
     This builds a dict with the minimal information needed to operate as a
     valid IPython user namespace, which you can pass to the various embedding
     classes in ipython.  The default implementation returns the same dict for
     both the locals and the globals to allow functions to refer to variables in
     the namespace.  Customized implementations can return different dicts.  The
     locals dictionary can actually be anything following the basic mapping
     protocol of a dict, but the globals dict must be a true dict, not even
     a subclass.  It is recommended that any custom object for the locals
     namespace synchronize with the globals dict somehow.
 
     Raises TypeError if the provided globals namespace is not a true dict.
 
     :Parameters:
         user_ns : dict-like, optional
             The current user namespace. The items in this namespace should be
             included in the output. If None, an appropriate blank namespace
             should be created.
         user_global_ns : dict, optional
             The current user global namespace. The items in this namespace
             should be included in the output. If None, an appropriate blank
             namespace should be created.
 
     :Returns:
         A tuple pair of dictionary-like object to be used as the local namespace
         of the interpreter and a dict to be used as the global namespace.
     """
 
     if user_ns is None:
         if make_user_ns is not _make_user_ns:
             # Old API overridden.
             # FIXME: Issue DeprecationWarning, or just let the old API live on?
             user_ns = make_user_ns(user_ns)
         else:
             # Set __name__ to __main__ to better match the behavior of the
             # normal interpreter.
             user_ns = {'__name__'     :'__main__',
                        '__builtins__' : __builtin__,
                        }
     else:
         user_ns.setdefault('__name__','__main__')
         user_ns.setdefault('__builtins__',__builtin__)
 
     if user_global_ns is None:
         if make_user_global_ns is not _make_user_global_ns:
             # Old API overridden.
             user_global_ns = make_user_global_ns(user_global_ns)
         else:
             user_global_ns = user_ns
     if type(user_global_ns) is not dict:
         raise TypeError("user_global_ns must be a true dict; got %r"
             % type(user_global_ns))
 
     return user_ns, user_global_ns
 
 
 def make_session(user_ns = None, shellclass = None):
     """Makes, but does not launch an IPython session.
     
     Later on you can call obj.mainloop() on the returned object.
 
     Inputs:
 
       - user_ns(None): a dict to be used as the user's namespace with initial
       data.
     
     WARNING: This should *not* be run when a session exists already."""
 
-    import IPython.Shell
+    import IPython.core.shell
     if shellclass is None:
-        return IPython.Shell.start(user_ns)
+        return IPython.core.shell.start(user_ns)
     return shellclass(user_ns = user_ns)

IPython/core/tests/test_imports.py

@@ -1,59 +1,62 b''
 #!/usr/bin/env python
 # encoding: utf-8
 
 def test_import_completer():
     from IPython.core import completer
 
 def test_import_crashhandler():
     from IPython.core import crashhandler
 
 def test_import_debugger():
     from IPython.core import debugger
 
 def test_import_fakemodule():
     from IPython.core import fakemodule
 
 def test_import_excolors():
     from IPython.core import excolors
 
 def test_import_history():
     from IPython.core import history
 
 def test_import_hooks():
     from IPython.core import hooks
 
 def test_import_ipapi():
     from IPython.core import ipapi
 
 def test_import_iplib():
     from IPython.core import iplib
 
 def test_import_ipmaker():
     from IPython.core import ipmaker
 
 def test_import_logger():
     from IPython.core import logger
 
 def test_import_macro():
     from IPython.core import macro
 
 def test_import_magic():
     from IPython.core import magic
 
 def test_import_oinspect():
     from IPython.core import oinspect
 
 def test_import_outputtrap():
     from IPython.core import outputtrap
 
 def test_import_prefilter():
     from IPython.core import prefilter
 
 def test_import_prompts():
     from IPython.core import prompts
 
 def test_import_release():
     from IPython.core import release
 
 def test_import_shadowns():
     from IPython.core import shadowns
+
+def test_import_shell():
+    from IPython.core import shell

IPython/gui/wx/ipshell_nonblocking.py

@@ -1,527 +1,527 b''
 #!/usr/bin/python
 # -*- coding: iso-8859-15 -*-
 '''
 Provides IPython remote instance.
 
 @author: Laurent Dufrechou
 laurent.dufrechou _at_ gmail.com
 @license: BSD
 
 All rights reserved. This program and the accompanying materials are made
 available under the terms of the BSD which accompanies this distribution, and
 is available at U{http://www.opensource.org/licenses/bsd-license.php}
 '''
 
 __version__ = 0.9
 __author__  = "Laurent Dufrechou"
 __email__   = "laurent.dufrechou _at_ gmail.com"
 __license__ = "BSD"
 
 import re
 import sys
 import os
 import locale
 from thread_ex import ThreadEx
 
 try:
     import IPython
     from IPython.utils import genutils
     from IPython.core import iplib
 except Exception,e:
     print "Error importing IPython (%s)" % str(e)
     raise Exception, e
 
 ##############################################################################
 class _Helper(object):
     """Redefine the built-in 'help'.
     This is a wrapper around pydoc.help (with a twist).
     """
 
     def __init__(self, pager):
         self._pager = pager
 
     def __repr__(self):
         return "Type help() for interactive help, " \
                "or help(object) for help about object."
     
     def __call__(self, *args, **kwds):
         class DummyWriter(object):
             '''Dumy class to handle help output'''	
             def __init__(self, pager):
                 self._pager = pager
                 
             def write(self, data):
                 '''hook to fill self._pager'''
                 self._pager(data)
 
         import pydoc
         pydoc.help.output = DummyWriter(self._pager)
         pydoc.help.interact = lambda :1
         
         return pydoc.help(*args, **kwds)
 
   
 ##############################################################################
 class _CodeExecutor(ThreadEx):
     ''' Thread that execute ipython code '''
     def __init__(self, instance):
         ThreadEx.__init__(self)
         self.instance = instance
         
     def run(self):
         '''Thread main loop'''
         try:
             self.instance._doc_text = None
             self.instance._help_text = None
             self.instance._execute()
             # used for uper class to generate event after execution
             self.instance._after_execute() 
             
         except KeyboardInterrupt:
             pass
  
 
 ##############################################################################
 class NonBlockingIPShell(object):
     '''
     Create an IPython instance, running the commands in a separate,
     non-blocking thread. 
     This allows embedding in any GUI without blockage.
 
     Note: The ThreadEx class supports asynchroneous function call
           via raise_exc()
     '''
 
     def __init__(self, argv=[], user_ns={}, user_global_ns=None,
                  cin=None, cout=None, cerr=None,
                  ask_exit_handler=None):
         '''
         @param argv: Command line options for IPython
         @type argv: list
         @param user_ns: User namespace.
         @type user_ns: dictionary
         @param user_global_ns: User global namespace.
         @type user_global_ns: dictionary.
         @param cin: Console standard input.
         @type cin: IO stream
         @param cout: Console standard output.
         @type cout: IO stream
         @param cerr: Console standard error.
         @type cerr: IO stream
         @param exit_handler: Replacement for builtin exit() function
         @type exit_handler: function
         @param time_loop: Define the sleep time between two thread's loop
         @type int
         '''
         #ipython0 initialisation
         self._IP = None
         self.init_ipython0(argv, user_ns, user_global_ns,
                           cin, cout, cerr,
                           ask_exit_handler)
         
         #vars used by _execute
         self._iter_more = 0
         self._history_level = 0
         self._complete_sep =  re.compile('[\s\{\}\[\]\(\)\=]')
         self._prompt = str(self._IP.outputcache.prompt1).strip()
 
         #thread working vars
         self._line_to_execute = ''
         self._threading = True
         
         #vars that will be checked by GUI loop to handle thread states...
         #will be replaced later by PostEvent GUI funtions...
         self._doc_text = None
         self._help_text = None
         self._add_button = None
 
     def init_ipython0(self, argv=[], user_ns={}, user_global_ns=None,
                      cin=None, cout=None, cerr=None,
                      ask_exit_handler=None):
         ''' Initialize an ipython0 instance '''
         
         #first we redefine in/out/error functions of IPython
         #BUG: we've got a limitation form ipython0 there
         #only one instance can be instanciated else tehre will be
         #cin/cout/cerr clash...
         if cin:
             genutils.Term.cin = cin
         if cout:
             genutils.Term.cout = cout
         if cerr:
             genutils.Term.cerr = cerr
         
         excepthook = sys.excepthook
 
         #Hack to save sys.displayhook, because ipython seems to overwrite it...
         self.sys_displayhook_ori = sys.displayhook
         
-        self._IP = IPython.Shell.make_IPython(
+        self._IP = IPython.shell.make_IPython(
                                     argv,user_ns=user_ns,
                                     user_global_ns=user_global_ns,
                                     embedded=True,
-                                    shell_class=IPython.Shell.InteractiveShell)
+                                    shell_class=IPython.shell.InteractiveShell)
 
         #we save ipython0 displayhook and we restore sys.displayhook
         self.displayhook = sys.displayhook
         sys.displayhook = self.sys_displayhook_ori
 
         #we replace IPython default encoding by wx locale encoding
         loc = locale.getpreferredencoding()
         if loc:
             self._IP.stdin_encoding = loc
         #we replace the ipython default pager by our pager
         self._IP.set_hook('show_in_pager', self._pager)
         
         #we replace the ipython default shell command caller 
         #by our shell handler
         self._IP.set_hook('shell_hook', self._shell)
         
         #we replace the ipython default input command caller by our method
         iplib.raw_input_original = self._raw_input_original
         #we replace the ipython default exit command by our method
         self._IP.exit = ask_exit_handler
         #we replace the help command
         self._IP.user_ns['help'] = _Helper(self._pager_help)
 
         #we disable cpase magic... until we found a way to use it properly.
         from IPython.core import ipapi
         ip = ipapi.get()
         def bypass_magic(self, arg):
             print '%this magic is currently disabled.'
         ip.expose_magic('cpaste', bypass_magic)
 
         import __builtin__
         __builtin__.raw_input = self._raw_input
         
         sys.excepthook = excepthook
 
     #----------------------- Thread management section ----------------------   
     def do_execute(self, line):
         """
         Tell the thread to process the 'line' command
         """
 
         self._line_to_execute = line
 
         if self._threading:
             #we launch the ipython line execution in a thread to make it 
             #interruptible with include it in self namespace to be able 
             #to call  ce.raise_exc(KeyboardInterrupt)
             self.ce = _CodeExecutor(self)
             self.ce.start()
         else:
             try:
                 self._doc_text = None
                 self._help_text = None
                 self._execute()
                 # used for uper class to generate event after execution
                 self._after_execute() 
             
             except KeyboardInterrupt:
                 pass
 
     #----------------------- IPython management section ----------------------
     def get_threading(self):
         """
         Returns threading status, is set to True, then each command sent to
         the interpreter will be executed in a separated thread allowing,
         for example, breaking a long running commands.
         Disallowing it, permits better compatibilty with instance that is embedding
         IPython instance.
 
         @return: Execution method
         @rtype: bool
         """
         return self._threading
     
     def set_threading(self, state):
         """
         Sets threading state, if set to True, then each command sent to
         the interpreter will be executed in a separated thread allowing,
         for example, breaking a long running commands.
         Disallowing it, permits better compatibilty with instance that is embedding
         IPython instance.
 
         @param state: Sets threading state
         @type bool
         """
         self._threading = state
 
     def get_doc_text(self):
         """
         Returns the output of the processing that need to be paged (if any)
 
         @return: The std output string.
         @rtype: string
         """
         return self._doc_text
         
     def get_help_text(self):
         """
         Returns the output of the processing that need to be paged via help pager(if any)
 
         @return: The std output string.
         @rtype: string
         """
         return self._help_text
 
     def get_banner(self):
         """
         Returns the IPython banner for useful info on IPython instance
 
         @return: The banner string.
         @rtype: string
         """
         return self._IP.BANNER
     
     def get_prompt_count(self):
         """
         Returns the prompt number.
         Each time a user execute a line in the IPython shell the prompt count is increased
 
         @return: The prompt number
         @rtype: int
         """
         return self._IP.outputcache.prompt_count
 
     def get_prompt(self):
         """
         Returns current prompt inside IPython instance
         (Can be In [...]: ot ...:)
 
         @return: The current prompt.
         @rtype: string
         """
         return self._prompt
 
     def get_indentation(self):
         """
         Returns the current indentation level
         Usefull to put the caret at the good start position if we want to do autoindentation.
 
         @return: The indentation level.
         @rtype: int
         """
         return self._IP.indent_current_nsp
         
     def update_namespace(self, ns_dict):
         '''
         Add the current dictionary to the shell namespace.
 
         @param ns_dict: A dictionary of symbol-values.
         @type ns_dict: dictionary
         '''
         self._IP.user_ns.update(ns_dict)
 
     def complete(self, line):
         '''
         Returns an auto completed line and/or posibilities for completion.
 
         @param line: Given line so far.
         @type line: string
 
         @return: Line completed as for as possible,
         and possible further completions.
         @rtype: tuple
         '''
         split_line = self._complete_sep.split(line)
         possibilities = self._IP.complete(split_line[-1])
         if possibilities:
 
             def _common_prefix(str1, str2):
                 '''
                 Reduction function. returns common prefix of two given strings.
 
                 @param str1: First string.
                 @type str1: string
                 @param str2: Second string
                 @type str2: string
 
                 @return: Common prefix to both strings.
                 @rtype: string
                 '''
                 for i in range(len(str1)):
                     if not str2.startswith(str1[:i+1]):
                         return str1[:i]
                 return str1
             common_prefix = reduce(_common_prefix, possibilities)
             completed = line[:-len(split_line[-1])]+common_prefix
         else:
             completed = line
         return completed, possibilities
 
     def history_back(self):
         '''
         Provides one history command back.
 
         @return: The command string.
         @rtype: string
         '''
         history = ''
         #the below while loop is used to suppress empty history lines
         while((history == '' or history == '\n') and self._history_level >0):
             if self._history_level >= 1:
                 self._history_level -= 1
             history = self._get_history()            
         return history
 
     def history_forward(self):
         '''
         Provides one history command forward.
 
         @return: The command string.
         @rtype: string
         '''
         history = ''
         #the below while loop is used to suppress empty history lines
         while((history == '' or history == '\n') \
         and self._history_level <= self._get_history_max_index()):
             if self._history_level < self._get_history_max_index():
                 self._history_level += 1
                 history = self._get_history()
             else:
                 if self._history_level == self._get_history_max_index():
                     history = self._get_history()
                     self._history_level += 1
                 else:
                     history = ''
         return history
 
     def init_history_index(self):
         '''
         set history to last command entered
         '''
         self._history_level = self._get_history_max_index()+1
 
     #----------------------- IPython PRIVATE management section --------------
     def _after_execute(self):
         '''
         Can be redefined to generate post event after excution is done
         '''
         pass
 
     def _ask_exit(self):
         '''
         Can be redefined to generate post event to exit the Ipython shell
         '''
         pass
 
     def _get_history_max_index(self):
         '''
         returns the max length of the history buffer
 
         @return: history length
         @rtype: int
         '''
         return len(self._IP.input_hist_raw)-1
         
     def _get_history(self):
         '''
         Get's the command string of the current history level.
 
         @return: Historic command stri
         @rtype: string
         '''
         rv = self._IP.input_hist_raw[self._history_level].strip('\n')
         return rv
 
     def _pager_help(self, text):
         '''
         This function is used as a callback replacment to IPython help pager function
 
         It puts the 'text' value inside the self._help_text string that can be retrived via
         get_help_text function.
         '''
         if self._help_text == None:
             self._help_text = text
         else:
             self._help_text += text
     
     def _pager(self, IP, text):
         '''
         This function is used as a callback replacment to IPython pager function
 
         It puts the 'text' value inside the self._doc_text string that can be retrived via
         get_doc_text function.
         '''
         self._doc_text = text
     
     def _raw_input_original(self, prompt=''):
         '''
         Custom raw_input() replacement. Get's current line from console buffer.
 
         @param prompt: Prompt to print. Here for compatability as replacement.
         @type prompt: string
 
         @return: The current command line text.
         @rtype: string
         '''
         return self._line_to_execute
 
     def _raw_input(self, prompt=''):
         """ A replacement from python's raw_input.
         """
         raise NotImplementedError
     
     def _execute(self):
         '''
         Executes the current line provided by the shell object.
         '''
 
         orig_stdout = sys.stdout
-        sys.stdout = IPython.Shell.Term.cout
+        sys.stdout = IPython.shell.Term.cout
         #self.sys_displayhook_ori = sys.displayhook
         #sys.displayhook = self.displayhook
         
         try:
             line = self._IP.raw_input(None, self._iter_more)
             if self._IP.autoindent:
                 self._IP.readline_startup_hook(None)
 
         except KeyboardInterrupt:
             self._IP.write('\nKeyboardInterrupt\n')
             self._IP.resetbuffer()
             # keep cache in sync with the prompt counter:
             self._IP.outputcache.prompt_count -= 1
 
             if self._IP.autoindent:
                 self._IP.indent_current_nsp = 0
             self._iter_more = 0
         except:
             self._IP.showtraceback()
         else:
             self._IP.write(str(self._IP.outputcache.prompt_out).strip())
             self._iter_more = self._IP.push(line)
             if (self._IP.SyntaxTB.last_syntax_error and \
                                                             self._IP.rc.autoedit_syntax):
                 self._IP.edit_syntax_error()
         if self._iter_more:
             self._prompt = str(self._IP.outputcache.prompt2).strip()
             if self._IP.autoindent:
                 self._IP.readline_startup_hook(self._IP.pre_readline)
         else:
             self._prompt = str(self._IP.outputcache.prompt1).strip()
             self._IP.indent_current_nsp = 0 #we set indentation to 0
 
         sys.stdout = orig_stdout
         #sys.displayhook = self.sys_displayhook_ori
                 
     def _shell(self, ip, cmd):
         '''
         Replacement method to allow shell commands without them blocking.
 
         @param ip: Ipython instance, same as self._IP
         @type cmd: Ipython instance
         @param cmd: Shell command to execute.
         @type cmd: string
         '''
         stdin, stdout = os.popen4(cmd)
         result = stdout.read().decode('cp437').\
                                             encode(locale.getpreferredencoding())
         #we use print command because the shell command is called
         #inside IPython instance and thus is redirected to thread cout
         #"\x01\x1b[1;36m\x02" <-- add colour to the text...
         print "\x01\x1b[1;36m\x02"+result
         stdout.close()
         stdin.close()

IPython/kernel/magic.py

@@ -1,171 +1,171 b''
 # encoding: utf-8
 
 """Magic command interface for interactive parallel work."""
 
 __docformat__ = "restructuredtext en"
 
 #-------------------------------------------------------------------------------
 #  Copyright (C) 2008  The IPython Development Team
 #
 #  Distributed under the terms of the BSD License.  The full license is in
 #  the file COPYING, distributed as part of this software.
 #-------------------------------------------------------------------------------
 
 #-------------------------------------------------------------------------------
 # Imports
 #-------------------------------------------------------------------------------
 
 import new
 
 from IPython.core.iplib import InteractiveShell
-from IPython.Shell import MTInteractiveShell
+from IPython.core.shell import MTInteractiveShell
 
 from twisted.internet.defer import Deferred
 
 
 #-------------------------------------------------------------------------------
 # Definitions of magic functions for use with IPython
 #-------------------------------------------------------------------------------
 
 NO_ACTIVE_CONTROLLER = """
 Error:  No Controller is activated
 Use activate() on a RemoteController object to activate it for magics.
 """
 
 def magic_result(self,parameter_s=''):
     """Print the result of command i on all engines of the active controller.
     
     To activate a controller in IPython, first create it and then call
     the activate() method.
     
     Then you can do the following:
     
     >>> result                                # Print the latest result
     Printing result... 
     [127.0.0.1:0] In [1]: b = 10
     [127.0.0.1:1] In [1]: b = 10
     
     >>> result 0                              # Print result 0
     In [14]: result 0
     Printing result... 
     [127.0.0.1:0] In [0]: a = 5
     [127.0.0.1:1] In [0]: a = 5
     """
     try:
         activeController = __IPYTHON__.activeController
     except AttributeError:
         print NO_ACTIVE_CONTROLLER
     else:
         try:
             index = int(parameter_s)
         except:
             index = None
         result = activeController.get_result(index)
         return result
 
 def magic_px(self,parameter_s=''):
     """Executes the given python command on the active IPython Controller.
     
     To activate a Controller in IPython, first create it and then call
     the activate() method.
     
     Then you can do the following:
      
     >>> %px a = 5       # Runs a = 5 on all nodes
     """
 
     try:
         activeController = __IPYTHON__.activeController
     except AttributeError:
         print NO_ACTIVE_CONTROLLER
     else:
         print "Parallel execution on engines: %s" % activeController.targets
         result = activeController.execute(parameter_s)
         return result
 
 def pxrunsource(self, source, filename="<input>", symbol="single"):
 
     try:
         code = self.compile(source, filename, symbol)
     except (OverflowError, SyntaxError, ValueError):
         # Case 1
         self.showsyntaxerror(filename)
         return None
 
     if code is None:
         # Case 2
         return True
 
     # Case 3
     # Because autopx is enabled, we now call executeAll or disable autopx if
     # %autopx or autopx has been called
     if '_ip.magic("%autopx' in source or '_ip.magic("autopx' in source:
         _disable_autopx(self)
         return False
     else:
         try:
             result = self.activeController.execute(source)
         except:
             self.showtraceback()
         else:
             print result.__repr__()
         return False
         
 def magic_autopx(self, parameter_s=''):
     """Toggles auto parallel mode for the active IPython Controller.
     
     To activate a Controller in IPython, first create it and then call
     the activate() method.
     
     Then you can do the following:
      
     >>> %autopx                    # Now all commands are executed in parallel
     Auto Parallel Enabled
     Type %autopx to disable
     ...
     >>> %autopx                    # Now all commands are locally executed
     Auto Parallel Disabled
     """
   
     if hasattr(self, 'autopx'):
         if self.autopx == True:
             _disable_autopx(self)
         else:
             _enable_autopx(self)
     else:
         _enable_autopx(self)
 
 def _enable_autopx(self):
     """Enable %autopx mode by saving the original runsource and installing 
     pxrunsource.
     """
     try:
         activeController = __IPYTHON__.activeController
     except AttributeError:
         print "No active RemoteController found, use RemoteController.activate()."
     else:
         self._original_runsource = self.runsource
         self.runsource = new.instancemethod(pxrunsource, self, self.__class__)
         self.autopx = True
         print "Auto Parallel Enabled\nType %autopx to disable"
 
 def _disable_autopx(self):
     """Disable %autopx by restoring the original runsource."""
     if hasattr(self, 'autopx'):
         if self.autopx == True:
             self.runsource = self._original_runsource
             self.autopx = False
             print "Auto Parallel Disabled"
             
 # Add the new magic function to the class dict:
 
 InteractiveShell.magic_result = magic_result
 InteractiveShell.magic_px = magic_px
 InteractiveShell.magic_autopx = magic_autopx
 
 # And remove the global name to keep global namespace clean.  Don't worry, the
 # copy bound to IPython stays, we're just removing the global name.
 del magic_result
 del magic_px
 del magic_autopx
 

IPython/testing/iptest.py

@@ -1,300 +1,300 b''
 # -*- coding: utf-8 -*-
 """IPython Test Suite Runner.
 
 This module provides a main entry point to a user script to test IPython
 itself from the command line. There are two ways of running this script:
 
 1. With the syntax `iptest all`.  This runs our entire test suite by
    calling this script (with different arguments) or trial recursively.  This
    causes modules and package to be tested in different processes, using nose
    or trial where appropriate.
 2. With the regular nose syntax, like `iptest -vvs IPython`.  In this form
    the script simply calls nose, but with special command line flags and
    plugins loaded.
 
 For now, this script requires that both nose and twisted are installed.  This
 will change in the future.
 """
 
 #-----------------------------------------------------------------------------
 # Module imports
 #-----------------------------------------------------------------------------
 
 import os
 import os.path as path
 import sys
 import subprocess
 import time
 import warnings
 
 import nose.plugins.builtin
 from nose.core import TestProgram
 
 from IPython.utils.platutils import find_cmd
 from IPython.testing.plugin.ipdoctest import IPythonDoctest
 
 pjoin = path.join
 
 #-----------------------------------------------------------------------------
 # Logic for skipping doctests
 #-----------------------------------------------------------------------------
 
 def test_for(mod):
     """Test to see if mod is importable."""
     try:
         __import__(mod)
     except ImportError:
         return False
     else:
         return True
 
 have_curses = test_for('_curses')
 have_wx = test_for('wx')
 have_zi = test_for('zope.interface')
 have_twisted = test_for('twisted')
 have_foolscap = test_for('foolscap')
 have_objc = test_for('objc')
 have_pexpect = test_for('pexpect')
 
 # For the IPythonDoctest plugin, we need to exclude certain patterns that cause
 # testing problems.  We should strive to minimize the number of skipped
 # modules, since this means untested code.  As the testing machinery
 # solidifies, this list should eventually become empty.
 EXCLUDE = [pjoin('IPython', 'external'),
            pjoin('IPython', 'frontend', 'process', 'winprocess.py'),
            pjoin('IPython_doctest_plugin'),
            pjoin('IPython', 'Gnuplot'),
            pjoin('IPython', 'Extensions', 'ipy_'),
            pjoin('IPython', 'Extensions', 'clearcmd'),
            pjoin('IPython', 'Extensions', 'PhysicalQInteractive'),
            pjoin('IPython', 'Extensions', 'scitedirector'),
            pjoin('IPython', 'Extensions', 'numeric_formats'),
            pjoin('IPython', 'testing', 'attic'),
            pjoin('IPython', 'testing', 'tutils'),
            pjoin('IPython', 'testing', 'tools'),
            pjoin('IPython', 'testing', 'mkdoctests')
            ]
 
 if not have_wx:
     EXCLUDE.append(pjoin('IPython', 'Extensions', 'igrid'))
     EXCLUDE.append(pjoin('IPython', 'gui'))
     EXCLUDE.append(pjoin('IPython', 'frontend', 'wx'))
 
 if not have_objc:
     EXCLUDE.append(pjoin('IPython', 'frontend', 'cocoa'))
 
 if not have_curses:
     EXCLUDE.append(pjoin('IPython', 'Extensions', 'ibrowse'))
 
 if not sys.platform == 'win32':
     EXCLUDE.append(pjoin('IPython', 'platutils_win32'))
 
 # These have to be skipped on win32 because the use echo, rm, cd, etc.
 # See ticket https://bugs.launchpad.net/bugs/366982
 if sys.platform == 'win32':
     EXCLUDE.append(pjoin('IPython', 'testing', 'plugin', 'test_exampleip'))
     EXCLUDE.append(pjoin('IPython', 'testing', 'plugin', 'dtexample'))
 
 if not os.name == 'posix':
     EXCLUDE.append(pjoin('IPython', 'platutils_posix'))
 
 if not have_pexpect:
     EXCLUDE.append(pjoin('IPython', 'lib', 'irunner'))
 
 # This is needed for the reg-exp to match on win32 in the ipdoctest plugin.
 if sys.platform == 'win32':
     EXCLUDE = [s.replace('\\','\\\\') for s in EXCLUDE]
 
 
 #-----------------------------------------------------------------------------
 # Functions and classes
 #-----------------------------------------------------------------------------
 
 def run_iptest():
     """Run the IPython test suite using nose.
     
     This function is called when this script is **not** called with the form
     `iptest all`.  It simply calls nose with appropriate command line flags
     and accepts all of the standard nose arguments.
     """
 
     warnings.filterwarnings('ignore', 
         'This will be removed soon.  Use IPython.testing.util instead')
 
     argv = sys.argv + [ 
                         # Loading ipdoctest causes problems with Twisted.
                         # I am removing this as a temporary fix to get the 
                         # test suite back into working shape.  Our nose
                         # plugin needs to be gone through with a fine
                         # toothed comb to find what is causing the problem.
                         '--with-ipdoctest',
                         '--ipdoctest-tests','--ipdoctest-extension=txt',
                         '--detailed-errors',
                        
                         # We add --exe because of setuptools' imbecility (it
                         # blindly does chmod +x on ALL files).  Nose does the
                         # right thing and it tries to avoid executables,
                         # setuptools unfortunately forces our hand here.  This
                         # has been discussed on the distutils list and the
                         # setuptools devs refuse to fix this problem!
                         '--exe',
                         ]
 
     # Detect if any tests were required by explicitly calling an IPython
     # submodule or giving a specific path
     has_tests = False
     for arg in sys.argv:
         if 'IPython' in arg or arg.endswith('.py') or \
            (':' in arg and  '.py' in arg):
             has_tests = True
             break
         
     # If nothing was specifically requested, test full IPython
     if not has_tests:
         argv.append('IPython')
 
     # Construct list of plugins, omitting the existing doctest plugin, which
     # ours replaces (and extends).
     plugins = [IPythonDoctest(EXCLUDE)]
     for p in nose.plugins.builtin.plugins:
         plug = p()
         if plug.name == 'doctest':
             continue
 
         #print '*** adding plugin:',plug.name  # dbg
         plugins.append(plug)
 
     TestProgram(argv=argv,plugins=plugins)
 
 
 class IPTester(object):
     """Call that calls iptest or trial in a subprocess.
     """
     def __init__(self,runner='iptest',params=None):
         """ """
         if runner == 'iptest':
             self.runner = ['iptest','-v']
         else:
             self.runner = [find_cmd('trial')]
         if params is None:
             params = []
         if isinstance(params,str):
             params = [params]
         self.params = params
 
         # Assemble call
         self.call_args = self.runner+self.params
 
     def run(self):
         """Run the stored commands"""
         return subprocess.call(self.call_args)
 
 
 def make_runners():
     """Define the modules and packages that need to be tested.
     """
     
     # This omits additional top-level modules that should not be doctested.
-    # XXX: Shell.py is also ommited because of a bug in the skip_doctest
+    # XXX: shell.py is also ommited because of a bug in the skip_doctest
     # decorator.  See ticket https://bugs.launchpad.net/bugs/366209
     top_mod = \
       ['backgroundjobs.py', 'coloransi.py', 'completer.py', 'configloader.py',
        'crashhandler.py', 'debugger.py', 'deepreload.py', 'demo.py',
        'DPyGetOpt.py', 'dtutils.py', 'excolors.py', 'fakemodule.py',
        'generics.py', 'genutils.py', 'history.py', 'hooks.py', 'ipapi.py',
        'iplib.py', 'ipmaker.py', 'ipstruct.py', 'Itpl.py',
        'logger.py', 'macro.py', 'magic.py', 'oinspect.py',
        'outputtrap.py', 'platutils.py', 'prefilter.py', 'prompts.py',
        'PyColorize.py', 'release.py', 'rlineimpl.py', 'shadowns.py',
        'shellglobals.py', 'strdispatch.py', 'twshell.py',
        'ultraTB.py', 'upgrade_dir.py', 'usage.py', 'wildcard.py',
        # See note above for why this is skipped
-       # 'Shell.py',
+       # 'shell.py',
        'winconsole.py']
 
     if have_pexpect:
         top_mod.append('irunner.py')
 
     if sys.platform == 'win32':
         top_mod.append('platutils_win32.py')
     elif os.name == 'posix':
         top_mod.append('platutils_posix.py')
     else:
         top_mod.append('platutils_dummy.py')
 
     # These are tested by nose, so skip IPython.kernel
     top_pack = ['config','Extensions','frontend',
                 'testing','tests','tools','UserConfig']
 
     if have_wx:
         top_pack.append('gui')
 
     modules  = ['IPython.%s' % m[:-3] for m in top_mod ]
     packages = ['IPython.%s' % m for m in top_pack ]
 
     # Make runners
     runners = dict(zip(top_pack, [IPTester(params=v) for v in packages]))
     
     # Test IPython.kernel using trial if twisted is installed
     if have_zi and have_twisted and have_foolscap:
         runners['trial'] = IPTester('trial',['IPython'])
 
     runners['modules'] = IPTester(params=modules)
 
     return runners
 
 
 def run_iptestall():
     """Run the entire IPython test suite by calling nose and trial.
     
     This function constructs :class:`IPTester` instances for all IPython
     modules and package and then runs each of them.  This causes the modules
     and packages of IPython to be tested each in their own subprocess using
     nose or twisted.trial appropriately.
     """
     runners = make_runners()
     # Run all test runners, tracking execution time
     failed = {}
     t_start = time.time()
     for name,runner in runners.iteritems():
         print '*'*77
         print 'IPython test set:',name
         res = runner.run()
         if res:
             failed[name] = res
     t_end = time.time()
     t_tests = t_end - t_start
     nrunners = len(runners)
     nfail = len(failed)
     # summarize results
     print
     print '*'*77
     print 'Ran %s test sets in %.3fs' % (nrunners, t_tests)
     print
     if not failed:
         print 'OK'
     else:
         # If anything went wrong, point out what command to rerun manually to
         # see the actual errors and individual summary
         print 'ERROR - %s out of %s test sets failed.' % (nfail, nrunners)
         for name in failed:
             failed_runner = runners[name]
             print '-'*40
             print 'Runner failed:',name
             print 'You may wish to rerun this one individually, with:'
             print ' '.join(failed_runner.call_args)
             print
 
 
 def main():
     if len(sys.argv) == 1:
         run_iptestall()
     else:
         if sys.argv[1] == 'all':
             run_iptestall()
         else:
             run_iptest()
 
 
 if __name__ == '__main__':
     main()
  No newline at end of file

IPython/testing/plugin/ipdoctest.py

@@ -1,909 +1,909 b''
 """Nose Plugin that supports IPython doctests.
 
 Limitations:
 
 - When generating examples for use as doctests, make sure that you have
   pretty-printing OFF.  This can be done either by starting ipython with the
   flag '--nopprint', by setting pprint to 0 in your ipythonrc file, or by
   interactively disabling it with %Pprint.  This is required so that IPython
   output matches that of normal Python, which is used by doctest for internal
   execution.
 
 - Do not rely on specific prompt numbers for results (such as using
   '_34==True', for example).  For IPython tests run via an external process the
   prompt numbers may be different, and IPython tests run as normal python code
   won't even have these special _NN variables set at all.
 """
 
 #-----------------------------------------------------------------------------
 # Module imports
 
 # From the standard library
 import __builtin__
 import commands
 import doctest
 import inspect
 import logging
 import os
 import re
 import sys
 import traceback
 import unittest
 
 from inspect import getmodule
 from StringIO import StringIO
 
 # We are overriding the default doctest runner, so we need to import a few
 # things from doctest directly
 from doctest import (REPORTING_FLAGS, REPORT_ONLY_FIRST_FAILURE,
                      _unittest_reportflags, DocTestRunner,
                      _extract_future_flags, pdb, _OutputRedirectingPdb,
                      _exception_traceback,
                      linecache)
 
 # Third-party modules
 import nose.core
 
 from nose.plugins import doctests, Plugin
 from nose.util import anyp, getpackage, test_address, resolve_name, tolist
 
 #-----------------------------------------------------------------------------
 # Module globals and other constants
 
 log = logging.getLogger(__name__)
 
 ###########################################################################
 # *** HACK ***
 # We must start our own ipython object and heavily muck with it so that all the
 # modifications IPython makes to system behavior don't send the doctest
 # machinery into a fit.  This code should be considered a gross hack, but it
 # gets the job done.
 
 def default_argv():
     """Return a valid default argv for creating testing instances of ipython"""
 
     # Get the install directory for the user configuration and tell ipython to
     # use the default profile from there.
     from IPython import UserConfig
     ipcdir = os.path.dirname(UserConfig.__file__)
     #ipconf = os.path.join(ipcdir,'ipy_user_conf.py')
     ipconf = os.path.join(ipcdir,'ipythonrc')
     #print 'conf:',ipconf # dbg
     
     return ['--colors=NoColor','--noterm_title','-rcfile=%s' % ipconf]
 
 
 # Hack to modify the %run command so we can sync the user's namespace with the
 # test globals.  Once we move over to a clean magic system, this will be done
 # with much less ugliness.
 
 class py_file_finder(object):
     def __init__(self,test_filename):
         self.test_filename = test_filename
         
     def __call__(self,name):
         from IPython.utils.genutils import get_py_filename
         try:
             return get_py_filename(name)
         except IOError:
             test_dir = os.path.dirname(self.test_filename)
             new_path = os.path.join(test_dir,name)
             return get_py_filename(new_path)
     
 
 def _run_ns_sync(self,arg_s,runner=None):
     """Modified version of %run that syncs testing namespaces.
 
     This is strictly needed for running doctests that call %run.
     """
 
     # When tests call %run directly (not via doctest) these function attributes
     # are not set
     try:
         fname = _run_ns_sync.test_filename
     except AttributeError:
         fname = arg_s
 
     finder = py_file_finder(fname)
     out = _ip.IP.magic_run_ori(arg_s,runner,finder)
     
     # Simliarly, there is no test_globs when a test is NOT a doctest
     if hasattr(_run_ns_sync,'test_globs'):
         _run_ns_sync.test_globs.update(_ip.user_ns)
     return out
 
 
 class ipnsdict(dict):
     """A special subclass of dict for use as an IPython namespace in doctests.
 
     This subclass adds a simple checkpointing capability so that when testing
     machinery clears it (we use it as the test execution context), it doesn't
     get completely destroyed.
     """
     
     def __init__(self,*a):
         dict.__init__(self,*a)
         self._savedict = {}
         
     def clear(self):
         dict.clear(self)
         self.update(self._savedict)
 
     def _checkpoint(self):
         self._savedict.clear()
         self._savedict.update(self)
 
     def update(self,other):
         self._checkpoint()
         dict.update(self,other)
 
         # If '_' is in the namespace, python won't set it when executing code,
         # and we have examples that test it.  So we ensure that the namespace
         # is always 'clean' of it before it's used for test code execution.
         self.pop('_',None)
 
         # The builtins namespace must *always* be the real __builtin__ module,
         # else weird stuff happens.  The main ipython code does have provisions
         # to ensure this after %run, but since in this class we do some
         # aggressive low-level cleaning of the execution namespace, we need to
         # correct for that ourselves, to ensure consitency with the 'real'
         # ipython.
         self['__builtins__'] = __builtin__
         
 
 def start_ipython():
     """Start a global IPython shell, which we need for IPython-specific syntax.
     """
 
     # This function should only ever run once!
     if hasattr(start_ipython,'already_called'):
         return
     start_ipython.already_called = True
 
     # Ok,  first time we're called, go ahead
     import new
 
     import IPython
     from IPython.core import ipapi
     
     def xsys(cmd):
         """Execute a command and print its output.
 
         This is just a convenience function to replace the IPython system call
         with one that is more doctest-friendly.
         """
         cmd = _ip.IP.var_expand(cmd,depth=1)
         sys.stdout.write(commands.getoutput(cmd))
         sys.stdout.flush()
 
     # Store certain global objects that IPython modifies
     _displayhook = sys.displayhook
     _excepthook = sys.excepthook
     _main = sys.modules.get('__main__')
 
     argv = default_argv()
     
     # Start IPython instance.  We customize it to start with minimal frills.
     user_ns,global_ns = ipapi.make_user_namespaces(ipnsdict(),dict())
-    IPython.Shell.IPShell(argv,user_ns,global_ns)
+    IPython.shell.IPShell(argv,user_ns,global_ns)
 
     # Deactivate the various python system hooks added by ipython for
     # interactive convenience so we don't confuse the doctest system
     sys.modules['__main__'] = _main
     sys.displayhook = _displayhook
     sys.excepthook = _excepthook
 
     # So that ipython magics and aliases can be doctested (they work by making
     # a call into a global _ip object)
     _ip = ipapi.get()
     __builtin__._ip = _ip
 
     # Modify the IPython system call with one that uses getoutput, so that we
     # can capture subcommands and print them to Python's stdout, otherwise the
     # doctest machinery would miss them.
     _ip.system = xsys
 
     # Also patch our %run function in.
     im = new.instancemethod(_run_ns_sync,_ip.IP, _ip.IP.__class__)
     _ip.IP.magic_run_ori = _ip.IP.magic_run
     _ip.IP.magic_run = im
 
 # The start call MUST be made here.  I'm not sure yet why it doesn't work if
 # it is made later, at plugin initialization time, but in all my tests, that's
 # the case.
 start_ipython()
 
 # *** END HACK ***
 ###########################################################################
 
 # Classes and functions
 
 def is_extension_module(filename):
     """Return whether the given filename is an extension module.
 
     This simply checks that the extension is either .so or .pyd.
     """
     return os.path.splitext(filename)[1].lower() in ('.so','.pyd')
 
 
 class DocTestSkip(object):
     """Object wrapper for doctests to be skipped."""
     
     ds_skip = """Doctest to skip.
     >>> 1 #doctest: +SKIP
     """
 
     def __init__(self,obj):
         self.obj = obj
 
     def __getattribute__(self,key):
         if key == '__doc__':
             return DocTestSkip.ds_skip
         else:
             return getattr(object.__getattribute__(self,'obj'),key)
 
 # Modified version of the one in the stdlib, that fixes a python bug (doctests
 # not found in extension modules, http://bugs.python.org/issue3158)
 class DocTestFinder(doctest.DocTestFinder):
 
     def _from_module(self, module, object):
         """
         Return true if the given object is defined in the given
         module.
         """
         if module is None:
             return True
         elif inspect.isfunction(object):
             return module.__dict__ is object.func_globals
         elif inspect.isbuiltin(object):
             return module.__name__ == object.__module__
         elif inspect.isclass(object):
             return module.__name__ == object.__module__
         elif inspect.ismethod(object):
             # This one may be a bug in cython that fails to correctly set the
             # __module__ attribute of methods, but since the same error is easy
             # to make by extension code writers, having this safety in place
             # isn't such a bad idea
             return module.__name__ == object.im_class.__module__
         elif inspect.getmodule(object) is not None:
             return module is inspect.getmodule(object)
         elif hasattr(object, '__module__'):
             return module.__name__ == object.__module__
         elif isinstance(object, property):
             return True # [XX] no way not be sure.
         else:
             raise ValueError("object must be a class or function")
 
     def _find(self, tests, obj, name, module, source_lines, globs, seen):
         """
         Find tests for the given object and any contained objects, and
         add them to `tests`.
         """
 
         if hasattr(obj,"skip_doctest"):
             #print 'SKIPPING DOCTEST FOR:',obj  # dbg
             obj = DocTestSkip(obj)
 
         doctest.DocTestFinder._find(self,tests, obj, name, module,
                                     source_lines, globs, seen)
 
         # Below we re-run pieces of the above method with manual modifications,
         # because the original code is buggy and fails to correctly identify
         # doctests in extension modules.
 
         # Local shorthands
         from inspect import isroutine, isclass, ismodule
 
         # Look for tests in a module's contained objects.
         if inspect.ismodule(obj) and self._recurse:
             for valname, val in obj.__dict__.items():
                 valname1 = '%s.%s' % (name, valname)
                 if ( (isroutine(val) or isclass(val))
                      and self._from_module(module, val) ):
 
                     self._find(tests, val, valname1, module, source_lines,
                                globs, seen)
 
         # Look for tests in a class's contained objects.
         if inspect.isclass(obj) and self._recurse:
             #print 'RECURSE into class:',obj  # dbg
             for valname, val in obj.__dict__.items():
                 # Special handling for staticmethod/classmethod.
                 if isinstance(val, staticmethod):
                     val = getattr(obj, valname)
                 if isinstance(val, classmethod):
                     val = getattr(obj, valname).im_func
 
                 # Recurse to methods, properties, and nested classes.
                 if ((inspect.isfunction(val) or inspect.isclass(val) or
                      inspect.ismethod(val) or
                       isinstance(val, property)) and
                       self._from_module(module, val)):
                     valname = '%s.%s' % (name, valname)
                     self._find(tests, val, valname, module, source_lines,
                                globs, seen)
 
 
 class IPDoctestOutputChecker(doctest.OutputChecker):
     """Second-chance checker with support for random tests.
     
     If the default comparison doesn't pass, this checker looks in the expected
     output string for flags that tell us to ignore the output.
     """
 
     random_re = re.compile(r'#\s*random\s+')
     
     def check_output(self, want, got, optionflags):
         """Check output, accepting special markers embedded in the output.
 
         If the output didn't pass the default validation but the special string
         '#random' is included, we accept it."""
 
         # Let the original tester verify first, in case people have valid tests
         # that happen to have a comment saying '#random' embedded in.
         ret = doctest.OutputChecker.check_output(self, want, got,
                                                  optionflags)
         if not ret and self.random_re.search(want):
             #print >> sys.stderr, 'RANDOM OK:',want  # dbg
             return True
 
         return ret
 
 
 class DocTestCase(doctests.DocTestCase):
     """Proxy for DocTestCase: provides an address() method that
     returns the correct address for the doctest case. Otherwise
     acts as a proxy to the test case. To provide hints for address(),
     an obj may also be passed -- this will be used as the test object
     for purposes of determining the test address, if it is provided.
     """
 
     # Note: this method was taken from numpy's nosetester module.
 
     # Subclass nose.plugins.doctests.DocTestCase to work around a bug in
     # its constructor that blocks non-default arguments from being passed
     # down into doctest.DocTestCase
 
     def __init__(self, test, optionflags=0, setUp=None, tearDown=None,
                  checker=None, obj=None, result_var='_'):
         self._result_var = result_var
         doctests.DocTestCase.__init__(self, test,
                                       optionflags=optionflags,
                                       setUp=setUp, tearDown=tearDown,
                                       checker=checker)
         # Now we must actually copy the original constructor from the stdlib
         # doctest class, because we can't call it directly and a bug in nose
         # means it never gets passed the right arguments.
 
         self._dt_optionflags = optionflags
         self._dt_checker = checker
         self._dt_test = test
         self._dt_setUp = setUp
         self._dt_tearDown = tearDown
 
         # XXX - store this runner once in the object!
         runner = IPDocTestRunner(optionflags=optionflags,
                                  checker=checker, verbose=False)
         self._dt_runner = runner
 
 
         # Each doctest should remember what directory it was loaded from...
         self._ori_dir = os.getcwd()
 
     # Modified runTest from the default stdlib
     def runTest(self):
         test = self._dt_test
         runner = self._dt_runner
         
         old = sys.stdout
         new = StringIO()
         optionflags = self._dt_optionflags
 
         if not (optionflags & REPORTING_FLAGS):
             # The option flags don't include any reporting flags,
             # so add the default reporting flags
             optionflags |= _unittest_reportflags
 
         try:
             # Save our current directory and switch out to the one where the
             # test was originally created, in case another doctest did a
             # directory change.  We'll restore this in the finally clause.
             curdir = os.getcwd()
             os.chdir(self._ori_dir)
 
             runner.DIVIDER = "-"*70
             failures, tries = runner.run(test,out=new.write,
                                          clear_globs=False)
         finally:
             sys.stdout = old
             os.chdir(curdir)
 
         if failures:
             raise self.failureException(self.format_failure(new.getvalue()))
 
     def setUp(self):
         """Modified test setup that syncs with ipython namespace"""
         
         if isinstance(self._dt_test.examples[0],IPExample):
             # for IPython examples *only*, we swap the globals with the ipython
             # namespace, after updating it with the globals (which doctest
             # fills with the necessary info from the module being tested).
             _ip.IP.user_ns.update(self._dt_test.globs)
             self._dt_test.globs = _ip.IP.user_ns
 
         doctests.DocTestCase.setUp(self)
 
 
 # A simple subclassing of the original with a different class name, so we can
 # distinguish and treat differently IPython examples from pure python ones.
 class IPExample(doctest.Example): pass
 
 
 class IPExternalExample(doctest.Example):
     """Doctest examples to be run in an external process."""
 
     def __init__(self, source, want, exc_msg=None, lineno=0, indent=0,
                  options=None):
         # Parent constructor
         doctest.Example.__init__(self,source,want,exc_msg,lineno,indent,options)
 
         # An EXTRA newline is needed to prevent pexpect hangs
         self.source += '\n'
 
 
 class IPDocTestParser(doctest.DocTestParser):
     """
     A class used to parse strings containing doctest examples.
 
     Note: This is a version modified to properly recognize IPython input and
     convert any IPython examples into valid Python ones.
     """
     # This regular expression is used to find doctest examples in a
     # string.  It defines three groups: `source` is the source code
     # (including leading indentation and prompts); `indent` is the
     # indentation of the first (PS1) line of the source code; and
     # `want` is the expected output (including leading indentation).
 
     # Classic Python prompts or default IPython ones
     _PS1_PY = r'>>>'
     _PS2_PY = r'\.\.\.'
 
     _PS1_IP = r'In\ \[\d+\]:'
     _PS2_IP = r'\ \ \ \.\.\.+:'
 
     _RE_TPL = r'''
         # Source consists of a PS1 line followed by zero or more PS2 lines.
         (?P<source>
             (?:^(?P<indent> [ ]*) (?P<ps1> %s) .*)    # PS1 line
             (?:\n           [ ]*  (?P<ps2> %s) .*)*)  # PS2 lines
         \n? # a newline
         # Want consists of any non-blank lines that do not start with PS1.
         (?P<want> (?:(?![ ]*$)    # Not a blank line
                      (?![ ]*%s)   # Not a line starting with PS1
                      (?![ ]*%s)   # Not a line starting with PS2
                      .*$\n?       # But any other line
                   )*)
                   '''
 
     _EXAMPLE_RE_PY = re.compile( _RE_TPL % (_PS1_PY,_PS2_PY,_PS1_PY,_PS2_PY),
                                  re.MULTILINE | re.VERBOSE)
 
     _EXAMPLE_RE_IP = re.compile( _RE_TPL % (_PS1_IP,_PS2_IP,_PS1_IP,_PS2_IP),
                                  re.MULTILINE | re.VERBOSE)
 
     # Mark a test as being fully random.  In this case, we simply append the
     # random marker ('#random') to each individual example's output.  This way
     # we don't need to modify any other code.
     _RANDOM_TEST = re.compile(r'#\s*all-random\s+')
 
     # Mark tests to be executed in an external process - currently unsupported.
     _EXTERNAL_IP = re.compile(r'#\s*ipdoctest:\s*EXTERNAL')
     
     def ip2py(self,source):
         """Convert input IPython source into valid Python."""
         out = []
         newline = out.append
         #print 'IPSRC:\n',source,'\n###'  # dbg
         # The input source must be first stripped of all bracketing whitespace
         # and turned into lines, so it looks to the parser like regular user
         # input
         for lnum,line in enumerate(source.strip().splitlines()):
             newline(_ip.IP.prefilter(line,lnum>0))
         newline('')  # ensure a closing newline, needed by doctest
         #print "PYSRC:", '\n'.join(out)  # dbg
         return '\n'.join(out)
 
     def parse(self, string, name='<string>'):
         """
         Divide the given string into examples and intervening text,
         and return them as a list of alternating Examples and strings.
         Line numbers for the Examples are 0-based.  The optional
         argument `name` is a name identifying this string, and is only
         used for error messages.
         """
 
         #print 'Parse string:\n',string # dbg
 
         string = string.expandtabs()
         # If all lines begin with the same indentation, then strip it.
         min_indent = self._min_indent(string)
         if min_indent > 0:
             string = '\n'.join([l[min_indent:] for l in string.split('\n')])
 
         output = []
         charno, lineno = 0, 0
 
         # We make 'all random' tests by adding the '# random' mark to every
         # block of output in the test.
         if self._RANDOM_TEST.search(string):
             random_marker = '\n# random'
         else:
             random_marker = ''
 
         # Whether to convert the input from ipython to python syntax
         ip2py = False
         # Find all doctest examples in the string.  First, try them as Python
         # examples, then as IPython ones
         terms = list(self._EXAMPLE_RE_PY.finditer(string))
         if terms:
             # Normal Python example
             #print '-'*70  # dbg
             #print 'PyExample, Source:\n',string  # dbg
             #print '-'*70  # dbg
             Example = doctest.Example
         else:
             # It's an ipython example.  Note that IPExamples are run
             # in-process, so their syntax must be turned into valid python.
             # IPExternalExamples are run out-of-process (via pexpect) so they
             # don't need any filtering (a real ipython will be executing them).
             terms = list(self._EXAMPLE_RE_IP.finditer(string))
             if self._EXTERNAL_IP.search(string):
                 #print '-'*70  # dbg
                 #print 'IPExternalExample, Source:\n',string  # dbg
                 #print '-'*70  # dbg
                 Example = IPExternalExample
             else:
                 #print '-'*70  # dbg
                 #print 'IPExample, Source:\n',string  # dbg
                 #print '-'*70  # dbg
                 Example = IPExample
                 ip2py = True
 
         for m in terms:
             # Add the pre-example text to `output`.
             output.append(string[charno:m.start()])
             # Update lineno (lines before this example)
             lineno += string.count('\n', charno, m.start())
             # Extract info from the regexp match.
             (source, options, want, exc_msg) = \
                      self._parse_example(m, name, lineno,ip2py)
 
             # Append the random-output marker (it defaults to empty in most
             # cases, it's only non-empty for 'all-random' tests):
             want += random_marker
                 
             if Example is IPExternalExample:
                 options[doctest.NORMALIZE_WHITESPACE] = True
                 want += '\n'
 
             # Create an Example, and add it to the list.
             if not self._IS_BLANK_OR_COMMENT(source):
                 output.append(Example(source, want, exc_msg,
                                       lineno=lineno,
                                       indent=min_indent+len(m.group('indent')),
                                       options=options))
             # Update lineno (lines inside this example)
             lineno += string.count('\n', m.start(), m.end())
             # Update charno.
             charno = m.end()
         # Add any remaining post-example text to `output`.
         output.append(string[charno:])
         return output
 
     def _parse_example(self, m, name, lineno,ip2py=False):
         """
         Given a regular expression match from `_EXAMPLE_RE` (`m`),
         return a pair `(source, want)`, where `source` is the matched
         example's source code (with prompts and indentation stripped);
         and `want` is the example's expected output (with indentation
         stripped).
 
         `name` is the string's name, and `lineno` is the line number
         where the example starts; both are used for error messages.
 
         Optional:
         `ip2py`: if true, filter the input via IPython to convert the syntax
         into valid python.
         """
 
         # Get the example's indentation level.
         indent = len(m.group('indent'))
 
         # Divide source into lines; check that they're properly
         # indented; and then strip their indentation & prompts.
         source_lines = m.group('source').split('\n')
 
         # We're using variable-length input prompts
         ps1 = m.group('ps1')
         ps2 = m.group('ps2')
         ps1_len = len(ps1)
 
         self._check_prompt_blank(source_lines, indent, name, lineno,ps1_len)
         if ps2:
             self._check_prefix(source_lines[1:], ' '*indent + ps2, name, lineno)
 
         source = '\n'.join([sl[indent+ps1_len+1:] for sl in source_lines])
 
         if ip2py:
             # Convert source input from IPython into valid Python syntax
             source = self.ip2py(source)
 
         # Divide want into lines; check that it's properly indented; and
         # then strip the indentation.  Spaces before the last newline should
         # be preserved, so plain rstrip() isn't good enough.
         want = m.group('want')
         want_lines = want.split('\n')
         if len(want_lines) > 1 and re.match(r' *$', want_lines[-1]):
             del want_lines[-1]  # forget final newline & spaces after it
         self._check_prefix(want_lines, ' '*indent, name,
                            lineno + len(source_lines))
 
         # Remove ipython output prompt that might be present in the first line
         want_lines[0] = re.sub(r'Out\[\d+\]: \s*?\n?','',want_lines[0])
 
         want = '\n'.join([wl[indent:] for wl in want_lines])
 
         # If `want` contains a traceback message, then extract it.
         m = self._EXCEPTION_RE.match(want)
         if m:
             exc_msg = m.group('msg')
         else:
             exc_msg = None
 
         # Extract options from the source.
         options = self._find_options(source, name, lineno)
 
         return source, options, want, exc_msg
 
     def _check_prompt_blank(self, lines, indent, name, lineno, ps1_len):
         """
         Given the lines of a source string (including prompts and
         leading indentation), check to make sure that every prompt is
         followed by a space character.  If any line is not followed by
         a space character, then raise ValueError.
 
         Note: IPython-modified version which takes the input prompt length as a
         parameter, so that prompts of variable length can be dealt with.
         """
         space_idx = indent+ps1_len
         min_len = space_idx+1
         for i, line in enumerate(lines):
             if len(line) >=  min_len and line[space_idx] != ' ':
                 raise ValueError('line %r of the docstring for %s '
                                  'lacks blank after %s: %r' %
                                  (lineno+i+1, name,
                                   line[indent:space_idx], line))
 
 
 SKIP = doctest.register_optionflag('SKIP')
 
 
 class IPDocTestRunner(doctest.DocTestRunner,object):
     """Test runner that synchronizes the IPython namespace with test globals.
     """
     
     def run(self, test, compileflags=None, out=None, clear_globs=True):
 
         # Hack: ipython needs access to the execution context of the example,
         # so that it can propagate user variables loaded by %run into
         # test.globs.  We put them here into our modified %run as a function
         # attribute.  Our new %run will then only make the namespace update
         # when called (rather than unconconditionally updating test.globs here
         # for all examples, most of which won't be calling %run anyway).
         _run_ns_sync.test_globs = test.globs
         _run_ns_sync.test_filename = test.filename
         
         return super(IPDocTestRunner,self).run(test,
                                                compileflags,out,clear_globs)
 
 
 class DocFileCase(doctest.DocFileCase):
     """Overrides to provide filename
     """
     def address(self):
         return (self._dt_test.filename, None, None)
 
 
 class ExtensionDoctest(doctests.Doctest):
     """Nose Plugin that supports doctests in extension modules.
     """
     name = 'extdoctest'   # call nosetests with --with-extdoctest
     enabled = True
 
     def __init__(self,exclude_patterns=None):
         """Create a new ExtensionDoctest plugin.
 
         Parameters
         ----------
 
         exclude_patterns : sequence of strings, optional
           These patterns are compiled as regular expressions, subsequently used
           to exclude any filename which matches them from inclusion in the test
           suite (using pattern.search(), NOT pattern.match() ).
         """
 
         if exclude_patterns is None:
             exclude_patterns = []
         self.exclude_patterns = map(re.compile,exclude_patterns)
         doctests.Doctest.__init__(self)
 
     def options(self, parser, env=os.environ):
         Plugin.options(self, parser, env)
         parser.add_option('--doctest-tests', action='store_true',
                           dest='doctest_tests',
                           default=env.get('NOSE_DOCTEST_TESTS',True),
                           help="Also look for doctests in test modules. "
                           "Note that classes, methods and functions should "
                           "have either doctests or non-doctest tests, "
                           "not both. [NOSE_DOCTEST_TESTS]")
         parser.add_option('--doctest-extension', action="append",
                           dest="doctestExtension",
                           help="Also look for doctests in files with "
                           "this extension [NOSE_DOCTEST_EXTENSION]")
         # Set the default as a list, if given in env; otherwise
         # an additional value set on the command line will cause
         # an error.
         env_setting = env.get('NOSE_DOCTEST_EXTENSION')
         if env_setting is not None:
             parser.set_defaults(doctestExtension=tolist(env_setting))
 
 
     def configure(self, options, config):
         Plugin.configure(self, options, config)
         self.doctest_tests = options.doctest_tests
         self.extension = tolist(options.doctestExtension)
 
         self.parser = doctest.DocTestParser()
         self.finder = DocTestFinder()
         self.checker = IPDoctestOutputChecker()
         self.globs = None
         self.extraglobs = None
 
 
     def loadTestsFromExtensionModule(self,filename):
         bpath,mod = os.path.split(filename)
         modname = os.path.splitext(mod)[0]
         try:
             sys.path.append(bpath)
             module = __import__(modname)
             tests = list(self.loadTestsFromModule(module))
         finally:
             sys.path.pop()
         return tests
 
     # NOTE: the method below is almost a copy of the original one in nose, with
     # a  few modifications to control output checking.
 
     def loadTestsFromModule(self, module):
         #print '*** ipdoctest - lTM',module  # dbg
         
         if not self.matches(module.__name__):
             log.debug("Doctest doesn't want module %s", module)
             return
 
         tests = self.finder.find(module,globs=self.globs,
                                  extraglobs=self.extraglobs)
         if not tests:
             return
 
         # always use whitespace and ellipsis options
         optionflags = doctest.NORMALIZE_WHITESPACE | doctest.ELLIPSIS
 
         tests.sort()
         module_file = module.__file__
         if module_file[-4:] in ('.pyc', '.pyo'):
             module_file = module_file[:-1]
         for test in tests:
             if not test.examples:
                 continue
             if not test.filename:
                 test.filename = module_file
             
             yield DocTestCase(test,
                               optionflags=optionflags,
                               checker=self.checker)
 
 
     def loadTestsFromFile(self, filename):
         if is_extension_module(filename):
             for t in self.loadTestsFromExtensionModule(filename):
                 yield t
         else:
             if self.extension and anyp(filename.endswith, self.extension):
                 name = os.path.basename(filename)
                 dh = open(filename)
                 try:
                     doc = dh.read()
                 finally:
                     dh.close()
                 test = self.parser.get_doctest(
                     doc, globs={'__file__': filename}, name=name,
                     filename=filename, lineno=0)
                 if test.examples:
                     #print 'FileCase:',test.examples  # dbg
                     yield DocFileCase(test)
                 else:
                     yield False # no tests to load
 
     def wantFile(self,filename):
         """Return whether the given filename should be scanned for tests.
 
         Modified version that accepts extension modules as valid containers for
         doctests.
         """
         # print '*** ipdoctest- wantFile:',filename  # dbg
 
         for pat in self.exclude_patterns:
             if pat.search(filename):
                 # print '###>>> SKIP:',filename  # dbg
                 return False
 
         if is_extension_module(filename):
             return True
         else:
             return doctests.Doctest.wantFile(self,filename)
 
 
 class IPythonDoctest(ExtensionDoctest):
     """Nose Plugin that supports doctests in extension modules.
     """
     name = 'ipdoctest'   # call nosetests with --with-ipdoctest
     enabled = True
     
     def makeTest(self, obj, parent):
         """Look for doctests in the given object, which will be a
         function, method or class.
         """
         # always use whitespace and ellipsis options
         optionflags = doctest.NORMALIZE_WHITESPACE | doctest.ELLIPSIS
 
         doctests = self.finder.find(obj, module=getmodule(parent))
         if doctests:
             for test in doctests:
                 if len(test.examples) == 0:
                     continue
 
                 yield DocTestCase(test, obj=obj,
                                   optionflags=optionflags,
                                   checker=self.checker)
 
     def options(self, parser, env=os.environ):
         Plugin.options(self, parser, env)
         parser.add_option('--ipdoctest-tests', action='store_true',
                           dest='ipdoctest_tests',
                           default=env.get('NOSE_IPDOCTEST_TESTS',True),
                           help="Also look for doctests in test modules. "
                           "Note that classes, methods and functions should "
                           "have either doctests or non-doctest tests, "
                           "not both. [NOSE_IPDOCTEST_TESTS]")
         parser.add_option('--ipdoctest-extension', action="append",
                           dest="ipdoctest_extension",
                           help="Also look for doctests in files with "
                           "this extension [NOSE_IPDOCTEST_EXTENSION]")
         # Set the default as a list, if given in env; otherwise
         # an additional value set on the command line will cause
         # an error.
         env_setting = env.get('NOSE_IPDOCTEST_EXTENSION')
         if env_setting is not None:
             parser.set_defaults(ipdoctest_extension=tolist(env_setting))
 
     def configure(self, options, config):
         Plugin.configure(self, options, config)
         self.doctest_tests = options.ipdoctest_tests
         self.extension = tolist(options.ipdoctest_extension)
 
         self.parser = IPDocTestParser()
         self.finder = DocTestFinder(parser=self.parser)
         self.checker = IPDoctestOutputChecker()
         self.globs = None
         self.extraglobs = None

IPython/usage.py

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