First prototype of component, traitlets and a config loader.

IPython/config/loader.py

@@ -0,0 +1,186 b''
+#!/usr/bin/env python
+# encoding: utf-8
+"""A factory for creating configuration objects.
+"""
+
+#-----------------------------------------------------------------------------
+#  Copyright (C) 2008-2009  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 os
+
+from IPython.utils.ipstruct import Struct
+
+#-----------------------------------------------------------------------------
+# Code
+#-----------------------------------------------------------------------------
+
+
+class ConfigLoaderError(Exception):
+    pass
+
+
+class ConfigLoader(object):
+    """A object for loading configurations from just about anywhere.
+    
+    The resulting configuration is packaged as a :class:`Struct`.
+    """
+
+    def __init__(self):
+        """A base class for config loaders.
+        
+        Examples
+        --------
+        
+        >>> cl = ConfigLoader()
+        >>> config = cl.load_config()
+        >>> config
+        {}
+        """
+        self.clear()
+
+    def clear(self):
+        self.config = Struct()
+
+    def load_config(self):
+        """Load a config from somewhere, return a Struct.
+        
+        Usually, this will cause self.config to be set and then returned.
+        """
+        return self.config
+
+
+class FileConfigLoader(ConfigLoader):
+    """A config loader for pure python files.
+    
+    This calls execfile on a plain python file and looks for attributes
+    that are all caps.  These attribute are added to the config Struct.
+    """
+
+    def __init__(self, filename, path='.'):
+        """Build a config loader for a filename and path.
+
+        Parameters
+        ----------
+        filename : str
+            The file name of the config file.
+        path : str, list, tuple
+            The path to search for the config file on, or a sequence of
+            paths to try in order
+
+        Examples
+        --------
+        
+        
+        """
+        self.filename = filename
+        self.path = path
+        self.full_filename = ''
+        self.data = None
+        ConfigLoader.__init__(self)
+
+    def find_file(self):
+        """Implement file finding logic here."""
+        self.full_filename = self.filename
+
+    def read_file_as_dict(self):
+        if not os.path.isfile(self.full_filename):
+            raise IOError("config file does not exist: %r" % self.fullfilename)
+        self.data = {}
+        execfile(self.full_filename, self.data)
+
+    def convert_to_struct(self):
+        if self.data is None:
+            ConfigLoaderError('self.data does not exist')
+        for k, v in self.data.iteritems():
+            if k == k.upper():
+                self.config[k] = v
+
+    def load_config(self):
+        self.find_file()
+        self.read_file_as_dict()
+        self.convert_to_struct()
+        return self.config
+
+class PyConfigLoader(object):
+    pass
+
+
+class DefaultFileConfigLoader(object):
+
+    def __init__(self, filename, install_location):
+        pass
+
+    def load_config(self):
+        pass
+
+    def install(self, force=False):
+        pass
+
+
+class CommandLineConfigLoader(ConfigLoader):
+
+    def __init__(self):
+        self.parser = None
+        self.parsed_data = None
+        self.clear()
+        
+
+    def clear(self):
+        self.config = Struct()
+
+    def load_config(self, args=None):
+        self.create_parser()
+        self.parse_args(args)
+        self.convert_to_struct()
+        return self.config
+
+    def create_parser(self):
+        """Create self.parser"""
+
+    def parse_args(self, args=None):
+        """self.parser->self.parsed_data"""
+        if self.parser is None:
+            raise ConfigLoaderError('self.parser does not exist')
+        if args is None:
+            self.parsed_data = parser.parse_args()
+        else:
+            self.parse_data = parser.parse_args(args)
+
+    def convert_to_struct(self):
+        """self.parsed_data->self.config"""
+        if self.parsed_data is None:
+            raise ConfigLoaderError('self.parsed_data does not exist')
+        self.config = Struct(vars(self.parsed_data))
+
+
+class ArgParseConfigLoader(CommandLineConfigLoader):
+
+    # arguments = [(('-f','--file'),dict(type=str,dest='file'))]
+    arguments = []
+
+    def __init__(self, *args, **kw):
+        """Create a config loader for use with argparse.
+        
+        The args and kwargs arguments here are passed onto the constructor
+        of :class:`argparse.ArgumentParser`.
+        """
+        self.args = args
+        self.kw = kw
+        CommandLineConfigLoader.__init__(self)
+
+    def create_parser(self):
+        self.parser = argparse.ArgumentParser(*self.args, **self.kw)
+        self.add_arguments()
+
+    def add_arguments(self):
+        for argument in self.arguments:
+            self.parser.add_argument(*argument[0],**argument[1])
+

IPython/core/component.py

@@ -0,0 +1,184 b''
+#!/usr/bin/env python
+# encoding: utf-8
+"""
+A lightweight component system for IPython.
+
+Authors:
+
+* Brian Granger
+* Fernando Perez
+"""
+
+#-----------------------------------------------------------------------------
+#  Copyright (C) 2008-2009  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
+#-----------------------------------------------------------------------------
+
+
+from weakref import WeakValueDictionary
+
+from IPython.utils.traitlets import (
+    HasTraitlets, TraitletError, MetaHasTraitlets,
+    Int, Float, Str, Bool, Unicode
+)
+
+
+#-----------------------------------------------------------------------------
+# Helper classes for Components
+#-----------------------------------------------------------------------------
+
+
+class Config(object):
+    pass
+
+
+class MetaComponentTracker(type):
+    """A metaclass that tracks instances of Components and its subclasses."""
+
+    def __init__(cls, name, bases, d):
+        super(MetaComponentTracker, cls).__init__(name, bases, d)
+        cls.__instance_refs = WeakValueDictionary()
+        cls.__numcreated = 0
+
+    def __call__(cls, *args, **kw):
+        """Called when class is called (instantiated)!!!
+        
+        Then a Component or subclass is instantiated, this is called and
+        the instance is saved in a WeakValueDictionary for tracking.
+        """
+
+        instance = super(MetaComponentTracker, cls).__call__(*args, **kw)
+        for c in cls.__mro__:
+            if issubclass(cls, c) and issubclass(c, Component):
+                c.__numcreated += 1
+                c.__instance_refs[c.__numcreated] = instance
+        return instance
+
+    def get_instances(cls):
+        """Get all instances of cls and its subclasses."""
+        return cls.__instance_refs.values()
+
+    def get_instances_by_name(cls, name):
+        """Get all instances of cls and its subclasses by name."""
+        return [i for i in cls.get_instances() if i.name == name]
+
+    def get_instances_by_subclass(cls, thisclass):
+        """Get all instances of cls that are instances of thisclass.
+        
+        This includes all instances of subclasses of thisclass.
+        """
+        return [i for i in cls.get_instances() if isinstance(i, thisclass)]
+
+    def get_instances_by_class(cls, thisclass):
+        """Get all instances of cls that are instances of thisclass.
+        
+        This exclused instances of thisclass subclasses.
+        """
+
+        return [i for i in cls.get_instances() if type(i) is thisclass]
+
+    def get_instances_by_condition(cls, call):
+        """Get all instances of cls, i such that call(i)==True."""
+        return [i for i in cls.get_instances() if call(i)]
+
+
+class ComponentNameGenerator(object):
+    """A Singleton to generate unique component names."""
+
+    def __init__(self, prefix):
+        self.prefix = prefix
+        self.i = 0
+
+    def __call__(self):
+        count = self.i
+        self.i += 1
+        return "%s%s" % (self.prefix, count)
+
+
+ComponentNameGenerator = ComponentNameGenerator('ipython.component')
+
+
+class MetaComponent(MetaHasTraitlets, MetaComponentTracker):
+    pass
+
+
+#-----------------------------------------------------------------------------
+# Component implementation
+#-----------------------------------------------------------------------------
+
+
+class Component(HasTraitlets):
+
+    __metaclass__ = MetaComponent
+
+    config = Config()
+
+    def __init__(self, parent, name=None, config=None):
+        """Create a component given a parent.
+
+        Parameters
+        ----------
+        parent : Component subclass
+            The parent in the component graph.  The parent is used
+            to get the root of the component graph.
+        name : str
+            The unique name of the component.  If empty, then a unique
+            one will be autogenerated.
+        config : Config
+            If this is empty, self.config = root.config, otherwise
+            self.config = config and root.config is ignored.  This argument 
+            should be used to pass the config to the root.  Otherwise, it
+            can be used to *override* the inheritance of root.config.  If a 
+            caller wants to modify root.config (not override), the caller
+            should make a copy and change attributes and then pass the copy
+            to this argument.  We might think about changing this behavior.
+        """
+        super(Component, self).__init__()
+        if name is None:
+            self._name = ComponentNameGenerator()
+        else:
+            self._name = name
+        self.parent = parent # this uses the property and handles None
+        if config is not None:
+            self.config = config
+        else:
+            if self.parent is not None:
+                self.config = self.parent.config
+
+    #-------------------------------------------------------------------------
+    # Properties
+    #-------------------------------------------------------------------------
+
+    def _set_name(self, name):
+        # This should use the ComponentNameGenerator to test for uniqueness
+        self._name = name
+
+    def _get_name(self):
+        return self._name
+
+    name = property(_get_name, _set_name)
+
+    def _set_parent(self, parent):
+        if parent is None:
+            self._parent = None
+            self._root = self
+        else:
+            assert isinstance(parent, Component), 'parent must be a component'
+            self._parent = parent
+            self._root = parent.root
+
+    def _get_parent(self):
+        return self._parent
+
+    parent = property(_get_parent, _set_parent)
+
+    @property
+    def root(self):
+        return self._root
+

IPython/utils/traitlets.py

@@ -0,0 +1,324 b''
+#!/usr/bin/env python
+# encoding: utf-8
+"""
+A lightweight Traits like module.
+
+Authors:
+
+* Brian Granger
+* Enthought, Inc.  Some of the code in this file comes from enthought.traits
+  and is licensed under the BSD license.  Also, many of the ideas also come
+  from enthought.traits even though our implementation is very different.
+"""
+
+#-----------------------------------------------------------------------------
+#  Copyright (C) 2008-2009  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 inspect
+import types
+from types import InstanceType
+
+#-----------------------------------------------------------------------------
+# Basic classes
+#-----------------------------------------------------------------------------
+
+
+class NoDefaultSpecified ( object ): pass
+NoDefaultSpecified = NoDefaultSpecified()
+
+
+class Undefined ( object ): pass
+Undefined = Undefined()
+
+
+class TraitletError(Exception):
+    pass
+
+
+#-----------------------------------------------------------------------------
+# Utilities
+#-----------------------------------------------------------------------------
+
+
+def class_of ( object ):
+    """ Returns a string containing the class name of an object with the
+    correct indefinite article ('a' or 'an') preceding it (e.g., 'an Image',
+    'a PlotValue').
+    """
+    if isinstance( object, basestring ):
+        return add_article( object )
+
+    return add_article( object.__class__.__name__ )
+
+
+def add_article ( name ):
+    """ Returns a string containing the correct indefinite article ('a' or 'an')
+    prefixed to the specified string.
+    """
+    if name[:1].lower() in 'aeiou':
+       return 'an ' + name
+
+    return 'a ' + name
+
+
+def repr_type(obj):
+    """ Return a string representation of a value and its type for readable
+    error messages.
+    """
+    the_type = type(obj)
+    if the_type is InstanceType:
+        # Old-style class.
+        the_type = obj.__class__
+    msg = '%r %r' % (obj, the_type)
+    return msg
+
+
+def parse_notifier_name(name):
+    if isinstance(name, str):
+        return [name]
+    elif name is None:
+        return ['anytraitlet']
+    elif isinstance(name, (list, tuple)):
+        for n in name:
+            assert isinstance(n, str), "names must be strings"
+        return name
+
+
+#-----------------------------------------------------------------------------
+# Base TraitletType for all traitlets
+#-----------------------------------------------------------------------------
+
+
+class TraitletType(object):
+
+    metadata = {}
+    default_value = None
+    info_text = 'any value'
+
+    # def __init__(self, name, default_value=NoDefaultSpecified, **metadata):
+    #     self.name = name
+    def __init__(self, default_value=NoDefaultSpecified, **metadata):
+        if default_value is not NoDefaultSpecified:
+            self.default_value = default_value
+        self.metadata.update(metadata)
+
+    def __get__(self, inst, cls=None):
+        if inst is None:
+            return self
+        else:
+            return inst._traitlet_values.get(self.name, self.default_value)
+
+    def __set__(self, inst, value):
+        new_value = self._validate(inst, value)
+        old_value = self.__get__(inst)
+        if old_value != new_value:
+            inst._traitlet_values[self.name] = new_value
+            inst._notify(self.name, old_value, value)
+
+    def _validate(self, inst, value):
+        if hasattr(self, 'validate'):
+            return self.validate(inst, value)
+        elif hasattr(self, 'is_valid_for'):
+            valid = self.is_valid_for(value)
+            if valid:
+                return value
+            else:
+                raise TraitletError('invalid value for type: %r' % value)
+        elif hasattr(self, 'value_for'):
+            return self.value_for(value)
+        else:
+            return value
+
+    def info(self):
+        return self.info_text
+
+    def error(self, obj, value):
+        if obj is not None:
+            e = "The '%s' traitlet of %s instance must be %s, but a value of %s was specified." \
+                % (self.name, class_of(obj),
+                   self.info(), repr_type(value))
+        else:
+            e = "The '%s' traitlet must be %s, but a value of %r was specified." \
+                % (self.name, self.info(), repr_type(value))            
+        raise TraitletError(e)
+
+
+#-----------------------------------------------------------------------------
+# The HasTraitlets implementation
+#-----------------------------------------------------------------------------
+
+
+class MetaHasTraitlets(type):
+    """A metaclass for HasTraitlets.
+    
+    This metaclass makes sure that any TraitletType class attributes are
+    instantiated and sets their name attribute.
+    """
+    
+    def __new__(mcls, name, bases, classdict):
+        for k,v in classdict.iteritems():
+            if isinstance(v, TraitletType):
+                v.name = k
+            elif inspect.isclass(v):
+                if issubclass(v, TraitletType):
+                    vinst = v()
+                    vinst.name = k
+                    classdict[k] = vinst
+        return super(MetaHasTraitlets, mcls).__new__(mcls, name, bases, classdict)
+
+
+class HasTraitlets(object):
+
+    __metaclass__ = MetaHasTraitlets
+
+    def __init__(self):
+        self._traitlet_values = {}
+        self._notifiers = {}
+
+    def _notify(self, name, old_value, new_value):
+        callables = self._notifiers.get(name,[])
+        more_callables = self._notifiers.get('anytraitlet',[])
+        callables.extend(more_callables)
+        for c in callables:
+            # Traits catches and logs errors here.  I allow them to raise
+            c(name, old_value, new_value)
+
+    def _add_notifiers(self, handler, name):
+        if not self._notifiers.has_key(name):
+            nlist = []
+            self._notifiers[name] = nlist
+        else:
+            nlist = self._notifiers[name]
+        if handler not in nlist:
+            nlist.append(handler)
+
+    def _remove_notifiers(self, handler, name):
+        if self._notifiers.has_key(name):
+            nlist = self._notifiers[name]
+            try:
+                index = nlist.index(handler)
+            except ValueError:
+                pass
+            else:
+                del nlist[index]
+
+    def on_traitlet_change(self, handler, name=None, remove=False):
+        if remove:
+            names = parse_notifier_name(name)
+            for n in names:
+                self._remove_notifiers(handler, n)
+        else:
+            names = parse_notifier_name(name)
+            for n in names:
+                self._add_notifiers(handler, n)
+
+
+#-----------------------------------------------------------------------------
+# Actual TraitletTypes implementations/subclasses
+#-----------------------------------------------------------------------------
+
+
+class Any(TraitletType):
+    default_value = None
+    info_text = 'any value'
+
+
+class Int(TraitletType):
+
+    evaluate = int
+    default_value = 0
+    info_text = 'an integer'
+
+    def validate(self, obj, value):
+        if isinstance(value, int):
+            return value
+        self.error(obj, value)
+
+
+class Long(TraitletType):
+
+    evaluate = long
+    default_value = 0L
+    info_text = 'a long'
+
+    def validate(self, obj, value):
+        if isinstance(value, long):
+            return value
+        if isinstance(value, int):
+            return long(value)
+        self.error(obj, value)
+
+
+class Float(TraitletType):
+
+    evaluate = float
+    default_value = 0.0
+    info_text = 'a float'
+
+    def validate(self, obj, value):
+        if isinstance(value, float):
+            return value
+        if isinstance(value, int):
+            return float(value)
+        self.error(obj, value)
+
+
+class Complex(TraitletType):
+
+    evaluate = complex
+    default_value = 0.0 + 0.0j
+    info_text = 'a complex number'
+
+    def validate(self, obj, value):
+        if isinstance(value, complex):
+            return value
+        if isinstance(value, (float, int)):
+            return complex(value)
+        self.error(obj, value)
+
+
+class Str(TraitletType):
+
+    evaluate = lambda x: x
+    default_value = ''
+    info_text = 'a string'
+
+    def validate(self, obj, value):
+        if isinstance(value, str):
+            return value
+        self.error(obj, value)
+
+
+class Unicode(TraitletType):
+
+    evaluate = unicode
+    default_value = u''
+    info_text = 'a unicode string'
+
+    def validate(self, obj, value):
+        if isinstance(value, unicode):
+            return value
+        if isinstance(value, str):
+            return unicode(value)
+        self.error(obj, value)
+
+
+class Bool(TraitletType):
+
+    evaluate = bool
+    default_value = False
+    info_text = 'a boolean'
+
+    def validate(self, obj, value):
+        if isinstance(value, bool):
+            return value
+        self.error(obj, value)
+

IPython/core/shell.py

@@ -1,273 +1,274 b''
-# -*- coding: utf-8 -*-
+#!/usr/bin/env python
+# encoding: utf-8
 """IPython Shell classes.
 
 Originally, this module was horribly complicated because of the need to
 use threads to integrate with GUI toolkit event loops.  Now, we are using
 the :mod:`IPython.lib.inputhook`, which is based on PyOS_InputHook.  This
 dramatically simplifies this logic and allow 3rd party packages (such as
 matplotlib) to handle these things by themselves.
 
 This new approach also allows projects like matplotlib to work interactively
 in the standard python shell.
 """
 
 #-----------------------------------------------------------------------------
 #  Copyright (C) 2008-2009  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 sys
 
 from IPython.core import ultratb
 from IPython.core import ipapi
 from IPython.utils.genutils import ask_yes_no
 from IPython.core.iplib import InteractiveShell
 from IPython.core.ipmaker import make_IPython
 
 #-----------------------------------------------------------------------------
 # Code
 #-----------------------------------------------------------------------------
 
 
 class IPShell:
     """Create an IPython instance.
 
     This calls the factory :func:`make_IPython`, which creates a configured
     :class:`InteractiveShell` object, and presents the result as a simple 
     class with a :meth:`mainloop` method.
     """
 
     def __init__(self, argv=None, user_ns=None, user_global_ns=None,
                  debug=1, shell_class=InteractiveShell):
         self.IP = make_IPython(argv, user_ns=user_ns,
                                user_global_ns=user_global_ns,
                                debug=debug, shell_class=shell_class)
 
     def mainloop(self,sys_exit=0,banner=None):
         self.IP.mainloop(banner)
         if sys_exit:
             sys.exit()
 
 
 # This is an additional magic that is exposed in embedded shells.
 def kill_embedded(self,parameter_s=''):
     """%kill_embedded : deactivate for good the current embedded IPython.
 
     This function (after asking for confirmation) sets an internal flag so that
     an embedded IPython will never activate again.  This is useful to
     permanently disable a shell that is being called inside a loop: once you've
     figured out what you needed from it, you may then kill it and the program
     will then continue to run without the interactive shell interfering again.
     """
     
     kill = ask_yes_no("Are you sure you want to kill this embedded instance "
                      "(y/n)? [y/N] ",'n')
     if kill:
         self.shell.embedded_active = False
         print "This embedded IPython will not reactivate anymore once you exit."
 
 
 class IPShellEmbed:
     """Allow embedding an IPython shell into a running program.
 
     Instances of this class are callable, with the __call__ method being an
     alias to the embed() method of an InteractiveShell instance.
 
     Usage (see also the example-embed.py file for a running example)::
 
         ipshell = IPShellEmbed([argv,banner,exit_msg,rc_override])
 
     * argv: list containing valid command-line options for IPython, as they
     would appear in sys.argv[1:].
 
     For example, the following command-line options::
 
         $ ipython -prompt_in1 'Input <\\#>' -colors LightBG
 
     would be passed in the argv list as::
 
         ['-prompt_in1','Input <\\#>','-colors','LightBG']
 
     * banner: string which gets printed every time the interpreter starts.
 
     * exit_msg: string which gets printed every time the interpreter exits.
 
     * rc_override: a dict or Struct of configuration options such as those
     used by IPython. These options are read from your ~/.ipython/ipythonrc
     file when the Shell object is created. Passing an explicit rc_override
     dict with any options you want allows you to override those values at
     creation time without having to modify the file. This way you can create
     embeddable instances configured in any way you want without editing any
     global files (thus keeping your interactive IPython configuration
     unchanged).
 
     Then the ipshell instance can be called anywhere inside your code::
     
         ipshell(header='') -> Opens up an IPython shell.
 
     * header: string printed by the IPython shell upon startup. This can let
     you know where in your code you are when dropping into the shell. Note
     that 'banner' gets prepended to all calls, so header is used for
     location-specific information.
 
     For more details, see the __call__ method below.
 
     When the IPython shell is exited with Ctrl-D, normal program execution
     resumes.
 
     This functionality was inspired by a posting on comp.lang.python by cmkl
     <[e-mail]> on Dec. 06/01 concerning similar uses of pyrepl, and
     by the IDL stop/continue commands.
     """
 
     def __init__(self, argv=None, banner='', exit_msg=None, 
                  rc_override=None, user_ns=None):
         """Note that argv here is a string, NOT a list."""
 
         self.set_banner(banner)
         self.set_exit_msg(exit_msg)
         self.set_dummy_mode(0)
 
         # sys.displayhook is a global, we need to save the user's original
         # Don't rely on __displayhook__, as the user may have changed that.
         self.sys_displayhook_ori = sys.displayhook
 
         # save readline completer status
         try:
             #print 'Save completer',sys.ipcompleter  # dbg
             self.sys_ipcompleter_ori = sys.ipcompleter
         except:
             pass # not nested with IPython
         
         self.IP = make_IPython(argv,rc_override=rc_override,
                                embedded=True,
                                user_ns=user_ns)
 
         ip = ipapi.IPApi(self.IP)
         ip.expose_magic("kill_embedded",kill_embedded)
 
         # copy our own displayhook also
         self.sys_displayhook_embed = sys.displayhook
         # and leave the system's display hook clean
         sys.displayhook = self.sys_displayhook_ori
         # don't use the ipython crash handler so that user exceptions aren't
         # trapped
         sys.excepthook = ultratb.FormattedTB(color_scheme = self.IP.rc.colors,
                                              mode = self.IP.rc.xmode,
                                              call_pdb = self.IP.rc.pdb)
         self.restore_system_completer()
 
     def restore_system_completer(self):
         """Restores the readline completer which was in place.
 
         This allows embedded IPython within IPython not to disrupt the
         parent's completion.
         """
         
         try:
             self.IP.readline.set_completer(self.sys_ipcompleter_ori)
             sys.ipcompleter = self.sys_ipcompleter_ori
         except:
             pass
 
     def __call__(self, header='', local_ns=None, global_ns=None, dummy=None):
         """Activate the interactive interpreter.
 
         __call__(self,header='',local_ns=None,global_ns,dummy=None) -> Start
         the interpreter shell with the given local and global namespaces, and
         optionally print a header string at startup.
 
         The shell can be globally activated/deactivated using the
         set/get_dummy_mode methods. This allows you to turn off a shell used
         for debugging globally.
 
         However, *each* time you call the shell you can override the current
         state of dummy_mode with the optional keyword parameter 'dummy'. For
         example, if you set dummy mode on with IPShell.set_dummy_mode(1), you
         can still have a specific call work by making it as IPShell(dummy=0).
 
         The optional keyword parameter dummy controls whether the call
         actually does anything.
         """
 
         # If the user has turned it off, go away
         if not self.IP.embedded_active:
             return
 
         # Normal exits from interactive mode set this flag, so the shell can't
         # re-enter (it checks this variable at the start of interactive mode).
         self.IP.exit_now = False
 
         # Allow the dummy parameter to override the global __dummy_mode
         if dummy or (dummy != 0 and self.__dummy_mode):
             return
 
         # Set global subsystems (display,completions) to our values
         sys.displayhook = self.sys_displayhook_embed
         if self.IP.has_readline:
             self.IP.set_completer()
 
         if self.banner and header:
             format = '%s\n%s\n'
         else:
             format = '%s%s\n'
         banner =  format % (self.banner,header)
 
         # Call the embedding code with a stack depth of 1 so it can skip over
         # our call and get the original caller's namespaces.
         self.IP.embed_mainloop(banner,local_ns,global_ns,stack_depth=1)
 
         if self.exit_msg:
             print self.exit_msg
             
         # Restore global systems (display, completion)
         sys.displayhook = self.sys_displayhook_ori
         self.restore_system_completer()
     
     def set_dummy_mode(self, dummy):
         """Sets the embeddable shell's dummy mode parameter.
 
         set_dummy_mode(dummy): dummy = 0 or 1.
 
         This parameter is persistent and makes calls to the embeddable shell
         silently return without performing any action. This allows you to
         globally activate or deactivate a shell you're using with a single call.
 
         If you need to manually"""
 
         if dummy not in [0,1,False,True]:
             raise ValueError,'dummy parameter must be boolean'
         self.__dummy_mode = dummy
 
     def get_dummy_mode(self):
         """Return the current value of the dummy mode parameter.
         """
         return self.__dummy_mode
     
     def set_banner(self, banner):
         """Sets the global banner.
 
         This banner gets prepended to every header printed when the shell
         instance is called."""
 
         self.banner = banner
 
     def set_exit_msg(self, exit_msg):
         """Sets the global exit_msg.
 
         This exit message gets printed upon exiting every time the embedded
         shell is called. It is None by default. """
 
         self.exit_msg = exit_msg
 
 # This is the one which should be called by external code.
 def start(user_ns = None):
     """Return a running shell instance of :class:`IPShell`."""
     return IPShell(user_ns = user_ns)