Merge branch 'config5' into trunk

IPython/config/application.py

@@ -0,0 +1,230 b''
+# encoding: utf-8
+"""
+A base class for a configurable application.
+
+Authors:
+
+* Brian Granger
+"""
+
+#-----------------------------------------------------------------------------
+#  Copyright (C) 2008-2011  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 copy import deepcopy
+import logging
+import sys
+
+from IPython.config.configurable import SingletonConfigurable
+from IPython.config.loader import (
+    KeyValueConfigLoader, PyFileConfigLoader, Config
+)
+
+from IPython.utils.traitlets import (
+    Unicode, List, Int, Enum, Dict
+)
+from IPython.utils.text import indent
+
+#-----------------------------------------------------------------------------
+# Descriptions for
+#-----------------------------------------------------------------------------
+
+flag_description = """
+Flags are command-line arguments passed as '--<flag>'.
+These take no parameters, unlike regular key-value arguments.
+They are typically used for setting boolean flags, or enabling
+modes that involve setting multiple options together.
+""".strip() # trim newlines of front and back
+
+alias_description = """
+These are commonly set parameters, given abbreviated aliases for convenience.
+They are set in the same `name=value` way as class parameters, where
+<name> is replaced by the real parameter for which it is an alias.
+""".strip() # trim newlines of front and back
+
+keyvalue_description = """
+Parameters are set from command-line arguments of the form:
+`Class.trait=value`.  Parameters will *never* be prefixed with '-'.
+This line is evaluated in Python, so simple expressions are allowed, e.g.
+    `C.a='range(3)'`   For setting C.a=[0,1,2]
+""".strip() # trim newlines of front and back
+
+#-----------------------------------------------------------------------------
+# Application class
+#-----------------------------------------------------------------------------
+
+
+class Application(SingletonConfigurable):
+    """A singleton application with full configuration support."""
+
+    # The name of the application, will usually match the name of the command
+    # line application
+    app_name = Unicode(u'application')
+
+    # The description of the application that is printed at the beginning
+    # of the help.
+    description = Unicode(u'This is an application.')
+    # default section descriptions
+    flag_description = Unicode(flag_description)
+    alias_description = Unicode(alias_description)
+    keyvalue_description = Unicode(keyvalue_description)
+    
+
+    # A sequence of Configurable subclasses whose config=True attributes will
+    # be exposed at the command line.
+    classes = List([])
+
+    # The version string of this application.
+    version = Unicode(u'0.0')
+
+    # The log level for the application
+    log_level = Enum((0,10,20,30,40,50), default_value=logging.WARN,
+                     config=True,
+                     help="Set the log level (0,10,20,30,40,50).")
+    
+    # the alias map for configurables
+    aliases = Dict(dict(log_level='Application.log_level'))
+    
+    # flags for loading Configurables or store_const style flags
+    # flags are loaded from this dict by '--key' flags
+    # this must be a dict of two-tuples, the first element being the Config/dict
+    # and the second being the help string for the flag
+    flags = Dict()
+    
+
+    def __init__(self, **kwargs):
+        SingletonConfigurable.__init__(self, **kwargs)
+        # Add my class to self.classes so my attributes appear in command line
+        # options.
+        self.classes.insert(0, self.__class__)
+        
+        # ensure self.flags dict is valid
+        for key,value in self.flags.iteritems():
+            assert len(value) == 2, "Bad flag: %r:%s"%(key,value)
+            assert isinstance(value[0], (dict, Config)), "Bad flag: %r:%s"%(key,value)
+            assert isinstance(value[1], basestring), "Bad flag: %r:%s"%(key,value)
+        self.init_logging()
+    
+    def init_logging(self):
+        """Start logging for this application.
+
+        The default is to log to stdout using a StreaHandler. The log level
+        starts at loggin.WARN, but this can be adjusted by setting the 
+        ``log_level`` attribute.
+        """
+        self.log = logging.getLogger(self.__class__.__name__)
+        self.log.setLevel(self.log_level)
+        self._log_handler = logging.StreamHandler()
+        self._log_formatter = logging.Formatter("[%(name)s] %(message)s")
+        self._log_handler.setFormatter(self._log_formatter)
+        self.log.addHandler(self._log_handler)
+
+    def _log_level_changed(self, name, old, new):
+        """Adjust the log level when log_level is set."""
+        self.log.setLevel(new)
+    
+    def print_alias_help(self):
+        """print the alias part of the help"""
+        if not self.aliases:
+            return
+            
+        print "Aliases"
+        print "-------"
+        print self.alias_description
+        print
+        
+        classdict = {}
+        for c in self.classes:
+            classdict[c.__name__] = c
+        
+        for alias, longname in self.aliases.iteritems():
+            classname, traitname = longname.split('.',1)
+            cls = classdict[classname]
+            
+            trait = cls.class_traits(config=True)[traitname]
+            help = trait.get_metadata('help')
+            print alias, "(%s)"%longname, ':', trait.__class__.__name__
+            if help:
+                print indent(help)
+        print
+    
+    def print_flag_help(self):
+        """print the flag part of the help"""
+        if not self.flags:
+            return
+        
+        print "Flags"
+        print "-----"
+        print self.flag_description
+        print
+        
+        for m, (cfg,help) in self.flags.iteritems():
+            print '--'+m
+            print indent(help)
+        print
+    
+    def print_help(self):
+        """Print the help for each Configurable class in self.classes."""
+        self.print_flag_help()
+        self.print_alias_help()
+        if self.classes:
+            print "Class parameters"
+            print "----------------"
+            print self.keyvalue_description
+            print
+        
+        for cls in self.classes:
+            cls.class_print_help()
+            print
+
+    def print_description(self):
+        """Print the application description."""
+        print self.description
+        print
+
+    def print_version(self):
+        """Print the version string."""
+        print self.version
+
+    def update_config(self, config):
+        """Fire the traits events when the config is updated."""
+        # Save a copy of the current config.
+        newconfig = deepcopy(self.config)
+        # Merge the new config into the current one.
+        newconfig._merge(config)
+        # Save the combined config as self.config, which triggers the traits
+        # events.
+        self.config = config
+
+    def parse_command_line(self, argv=None):
+        """Parse the command line arguments."""
+        argv = sys.argv[1:] if argv is None else argv
+
+        if '-h' in argv or '--help' in argv:
+            self.print_description()
+            self.print_help()
+            sys.exit(1)
+
+        if '--version' in argv:
+            self.print_version()
+            sys.exit(1)
+        
+        loader = KeyValueConfigLoader(argv=argv, aliases=self.aliases,
+                                        flags=self.flags)
+        config = loader.load_config()
+        self.update_config(config)
+
+    def load_config_file(self, filename, path=None):
+        """Load a .py based config file by filename and path."""
+        # TODO: this raises IOError if filename does not exist.
+        loader = PyFileConfigLoader(filename, path=path)
+        config = loader.load_config()
+        self.update_config(config)
+

IPython/config/tests/test_application.py

@@ -0,0 +1,105 b''
+"""
+Tests for IPython.config.application.Application
+
+Authors:
+
+* Brian Granger
+"""
+
+#-----------------------------------------------------------------------------
+#  Copyright (C) 2008-2011  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 unittest import TestCase
+
+from IPython.config.configurable import Configurable
+
+from IPython.config.application import (
+    Application
+)
+
+from IPython.utils.traitlets import (
+    Bool, Unicode, Int, Float, List, Dict
+)
+
+#-----------------------------------------------------------------------------
+# Code
+#-----------------------------------------------------------------------------
+
+class Foo(Configurable):
+
+    i = Int(0, config=True, help="The integer i.")
+    j = Int(1, config=True, help="The integer j.")
+    name = Unicode(u'Brian', config=True, help="First name.")
+
+
+class Bar(Configurable):
+
+    enabled = Bool(True, config=True, help="Enable bar.")
+
+
+class MyApp(Application):
+
+    app_name = Unicode(u'myapp')
+    running = Bool(False, config=True,
+                   help="Is the app running?")
+    classes = List([Bar, Foo])
+    config_file = Unicode(u'', config=True,
+                   help="Load this config file")
+
+    aliases = Dict(dict(i='Foo.i',j='Foo.j',name='Foo.name',
+                    enabled='Bar.enabled', log_level='MyApp.log_level'))
+    
+    flags = Dict(dict(enable=({'Bar': {'enabled' : True}}, "Set Bar.enabled to True"),
+                  disable=({'Bar': {'enabled' : False}}, "Set Bar.enabled to False")))
+    
+    def init_foo(self):
+        self.foo = Foo(config=self.config)
+
+    def init_bar(self):
+        self.bar = Bar(config=self.config)
+
+
+class TestApplication(TestCase):
+
+    def test_basic(self):
+        app = MyApp()
+        self.assertEquals(app.app_name, u'myapp')
+        self.assertEquals(app.running, False)
+        self.assertEquals(app.classes, [MyApp,Bar,Foo])
+        self.assertEquals(app.config_file, u'')
+
+    def test_config(self):
+        app = MyApp()
+        app.parse_command_line(["i=10","Foo.j=10","enabled=False","log_level=0"])
+        config = app.config
+        self.assertEquals(config.Foo.i, 10)
+        self.assertEquals(config.Foo.j, 10)
+        self.assertEquals(config.Bar.enabled, False)
+        self.assertEquals(config.MyApp.log_level,0)
+
+    def test_config_propagation(self):
+        app = MyApp()
+        app.parse_command_line(["i=10","Foo.j=10","enabled=False","log_level=0"])
+        app.init_foo()
+        app.init_bar()
+        self.assertEquals(app.foo.i, 10)
+        self.assertEquals(app.foo.j, 10)
+        self.assertEquals(app.bar.enabled, False)
+
+    def test_alias(self):
+        app = MyApp()
+        app.parse_command_line(["--disable"])
+        app.init_bar()
+        self.assertEquals(app.bar.enabled, False)
+        app.parse_command_line(["--enable"])
+        app.init_bar()
+        self.assertEquals(app.bar.enabled, True)
+    

docs/examples/core/appconfig.py

@@ -0,0 +1,96 b''
+"""A simple example of how to use IPython.config.application.Application.
+
+This should serve as a simple example that shows how the IPython config
+system works. The main classes are:
+
+* IPython.config.configurable.Configurable
+* IPython.config.configurable.SingletonConfigurable
+* IPython.config.loader.Config
+* IPython.config.application.Application
+
+To see the command line option help, run this program from the command line::
+
+    $ python appconfig.py -h
+
+To make one of your classes configurable (from the command line and config
+files) inherit from Configurable and declare class attributes as traits (see
+classes Foo and Bar below). To make the traits configurable, you will need
+to set the following options:
+
+* ``config``: set to ``True`` to make the attribute configurable.
+* ``shortname``: by default, configurable attributes are set using the syntax
+  "Classname.attributename". At the command line, this is a bit verbose, so
+  we allow "shortnames" to be declared. Setting a shortname is optional, but
+  when you do this, you can set the option at the command line using the
+  syntax: "shortname=value".
+* ``help``: set the help string to display a help message when the ``-h``
+  option is given at the command line. The help string should be valid ReST.
+
+When the config attribute of an Application is updated, it will fire all of
+the trait's events for all of the config=True attributes.
+"""
+
+import sys
+
+from IPython.config.configurable import Configurable
+from IPython.config.application import Application
+from IPython.utils.traitlets import (
+    Bool, Unicode, Int, Float, List, Dict
+)
+
+
+class Foo(Configurable):
+    """A class that has configurable, typed attributes.
+
+    """
+
+    i = Int(0, config=True, help="The integer i.")
+    j = Int(1, config=True, help="The integer j.")
+    name = Unicode(u'Brian', config=True, help="First name.")
+
+
+class Bar(Configurable):
+
+    enabled = Bool(True, config=True, help="Enable bar.")
+
+
+class MyApp(Application):
+
+    app_name = Unicode(u'myapp')
+    running = Bool(False, config=True,
+                   help="Is the app running?")
+    classes = List([Bar, Foo])
+    config_file = Unicode(u'', config=True,
+                   help="Load this config file")
+    
+    aliases = Dict(dict(i='Foo.i',j='Foo.j',name='Foo.name', running='MyApp.running',
+                        enabled='Bar.enabled', log_level='MyApp.log_level'))
+    
+    flags = Dict(dict(enable=({'Bar': {'enabled' : True}}, "Enable Bar"),
+                  disable=({'Bar': {'enabled' : False}}, "Disable Bar"),
+                  debug=({'MyApp':{'log_level':10}}, "Set loglevel to DEBUG")
+            ))
+    
+    def init_foo(self):
+        # Pass config to other classes for them to inherit the config.
+        self.foo = Foo(config=self.config)
+
+    def init_bar(self):
+        # Pass config to other classes for them to inherit the config.
+        self.bar = Bar(config=self.config)
+
+
+
+def main():
+    app = MyApp()
+    app.parse_command_line()
+    if app.config_file:
+        app.load_config_file(app.config_file)
+    app.init_foo()
+    app.init_bar()
+    print "app.config:"
+    print app.config
+
+
+if __name__ == "__main__":
+    main()

IPython/config/configurable.py

@@ -22,11 +22,10 b' Authors:'
 
 from copy import deepcopy
 import datetime
-from weakref import WeakValueDictionary
 
-from IPython.utils.importstring import import_item
 from loader import Config
 from IPython.utils.traitlets import HasTraits, Instance
+from IPython.utils.text import indent
 
 
 #-----------------------------------------------------------------------------
@@ -38,6 +37,9 b' class ConfigurableError(Exception):'
     pass
 
 
+class MultipleInstanceError(ConfigurableError):
+    pass
+
 #-----------------------------------------------------------------------------
 # Configurable implementation
 #-----------------------------------------------------------------------------
@@ -137,3 +139,87 b' class Configurable(HasTraits):'
                         # shared by all instances, effectively making it a class attribute.
                         setattr(self, k, deepcopy(config_value))
 
+    @classmethod
+    def class_get_help(cls):
+        """Get the help string for this class in ReST format."""
+        cls_traits = cls.class_traits(config=True)
+        final_help = []
+        final_help.append(u'%s options' % cls.__name__)
+        final_help.append(len(final_help[0])*u'-')
+        for k, v in cls_traits.items():
+            help = v.get_metadata('help')
+            header = "%s.%s : %s" % (cls.__name__, k, v.__class__.__name__)
+            final_help.append(header)
+            if help is not None:
+                final_help.append(indent(help))
+        return '\n'.join(final_help)
+
+    @classmethod
+    def class_print_help(cls):
+        print cls.class_get_help()
+
+
+class SingletonConfigurable(Configurable):
+    """A configurable that only allows one instance.
+
+    This class is for classes that should only have one instance of itself
+    or *any* subclass. To create and retrieve such a class use the
+    :meth:`SingletonConfigurable.instance` method.
+    """
+
+    _instance = None
+
+    @classmethod
+    def instance(cls, *args, **kwargs):
+        """Returns a global instance of this class.
+
+        This method create a new instance if none have previously been created
+        and returns a previously created instance is one already exists.
+
+        The arguments and keyword arguments passed to this method are passed
+        on to the :meth:`__init__` method of the class upon instantiation.
+
+        Examples
+        --------
+
+        Create a singleton class using instance, and retrieve it::
+
+            >>> from IPython.config.configurable import SingletonConfigurable
+            >>> class Foo(SingletonConfigurable): pass
+            >>> foo = Foo.instance()
+            >>> foo == Foo.instance()
+            True
+
+        Create a subclass that is retrived using the base class instance::
+
+            >>> class Bar(SingletonConfigurable): pass
+            >>> class Bam(Bar): pass
+            >>> bam = Bam.instance()
+            >>> bam == Bar.instance()
+            True
+        """
+        # Create and save the instance
+        if cls._instance is None:
+            inst = cls(*args, **kwargs)
+            # Now make sure that the instance will also be returned by
+            # the subclasses instance attribute.
+            for subclass in cls.mro():
+                if issubclass(cls, subclass) and \
+                issubclass(subclass, SingletonConfigurable) and \
+                subclass != SingletonConfigurable:
+                    subclass._instance = inst
+                else:
+                    break
+        if isinstance(cls._instance, cls):
+            return cls._instance
+        else:
+            raise MultipleInstanceError(
+                'Multiple incompatible subclass instances of '
+                '%s are being created.' % cls.__name__
+            )
+
+    @classmethod
+    def initialized(cls):
+        """Has an instance been created?"""
+        return hasattr(cls, "_instance") and cls._instance is not None
+

IPython/config/loader.py

@@ -1,5 +1,3 b''
-# -*- coding: utf-8 -*-
-# coding: utf-8
 """A simple configuration system.
 
 Authors
@@ -20,7 +18,7 b' Authors'
 #-----------------------------------------------------------------------------
 
 import __builtin__
-import os
+import re
 import sys
 
 from IPython.external import argparse
@@ -306,8 +304,117 b' class CommandLineConfigLoader(ConfigLoader):'
     here.
     """
 
+kv_pattern = re.compile(r'[A-Za-z]\w*(\.\w+)*\=.+')
+flag_pattern = re.compile(r'\-\-\w+(\-\w)*')
+
+class KeyValueConfigLoader(CommandLineConfigLoader):
+    """A config loader that loads key value pairs from the command line.
+
+    This allows command line options to be gives in the following form::
+    
+        ipython Global.profile="foo" InteractiveShell.autocall=False
+    """
+
+    def __init__(self, argv=None, aliases=None, flags=None):
+        """Create a key value pair config loader.
+
+        Parameters
+        ----------
+        argv : list
+            A list that has the form of sys.argv[1:] which has unicode
+            elements of the form u"key=value". If this is None (default),
+            then sys.argv[1:] will be used.
+        aliases : dict
+            A dict of aliases for configurable traits.
+            Keys are the short aliases, Values are the resolved trait.
+            Of the form: `{'alias' : 'Configurable.trait'}`
+        flags : dict
+            A dict of flags, keyed by str name. Vaues can be Config objects,
+            dicts, or "key=value" strings.  If Config or dict, when the flag
+            is triggered, The flag is loaded as `self.config.update(m)`.
+
+        Returns
+        -------
+        config : Config
+            The resulting Config object.
+
+        Examples
+        --------
+
+            >>> from IPython.config.loader import KeyValueConfigLoader
+            >>> cl = KeyValueConfigLoader()
+            >>> cl.load_config(["foo='bar'","A.name='brian'","B.number=0"])
+            {'A': {'name': 'brian'}, 'B': {'number': 0}, 'foo': 'bar'}
+        """
+        if argv is None:
+            argv = sys.argv[1:]
+        self.argv = argv
+        self.aliases = aliases or {}
+        self.flags = flags or {}
+
+    def load_config(self, argv=None, aliases=None, flags=None):
+        """Parse the configuration and generate the Config object.
+
+        Parameters
+        ----------
+        argv : list, optional
+            A list that has the form of sys.argv[1:] which has unicode
+            elements of the form u"key=value". If this is None (default),
+            then self.argv will be used.
+        aliases : dict
+            A dict of aliases for configurable traits.
+            Keys are the short aliases, Values are the resolved trait.
+            Of the form: `{'alias' : 'Configurable.trait'}`
+        flags : dict
+            A dict of flags, keyed by str name. Values can be Config objects
+            or dicts.  When the flag is triggered, The config is loaded as 
+            `self.config.update(cfg)`.
+        """
+        from IPython.config.configurable import Configurable
+
+        self.clear()
+        if argv is None:
+            argv = self.argv
+        if aliases is None:
+            aliases = self.aliases
+        if flags is None:
+            flags = self.flags
+
+        for item in argv:
+            if kv_pattern.match(item):
+                lhs,rhs = item.split('=',1)
+                # Substitute longnames for aliases.
+                if lhs in aliases:
+                    lhs = aliases[lhs]
+                exec_str = 'self.config.' + lhs + '=' + rhs
+                try:
+                    # Try to see if regular Python syntax will work. This
+                    # won't handle strings as the quote marks are removed
+                    # by the system shell.
+                    exec exec_str in locals(), globals()
+                except (NameError, SyntaxError):
+                    # This case happens if the rhs is a string but without
+                    # the quote marks.  We add the quote marks and see if
+                    # it succeeds. If it still fails, we let it raise.
+                    exec_str = 'self.config.' + lhs + '="' + rhs + '"'
+                    exec exec_str in locals(), globals()
+            elif flag_pattern.match(item):
+                # trim leading '--'
+                m = item[2:]
+                cfg,_ = flags.get(m, (None,None))
+                if cfg is None:
+                    raise ValueError("Unrecognized flag: %r"%item)
+                elif isinstance(cfg, (dict, Config)):
+                    # update self.config with Config:
+                    self.config.update(cfg)
+                else:
+                    raise ValueError("Invalid flag: %r"%flag)
+            else:
+                raise ValueError("Invalid argument: %r"%item)
+        return self.config
 
 class ArgParseConfigLoader(CommandLineConfigLoader):
+    """A loader that uses the argparse module to load from the command line."""
 
     def __init__(self, argv=None, *parser_args, **parser_kw):
         """Create a config loader for use with argparse.
@@ -326,6 +433,11 b' class ArgParseConfigLoader(CommandLineConfigLoader):'
         parser_kw : dict
           A tuple of keyword arguments that will be passed to the
           constructor of :class:`argparse.ArgumentParser`.
+
+        Returns
+        -------
+        config : Config
+            The resulting Config object.
         """
         super(CommandLineConfigLoader, self).__init__()
         if argv == None:
@@ -337,8 +449,8 b' class ArgParseConfigLoader(CommandLineConfigLoader):'
         kwargs.update(parser_kw)
         self.parser_kw = kwargs
 
-    def load_config(self, args=None):
-        """Parse command line arguments and return as a Struct.
+    def load_config(self, argv=None):
+        """Parse command line arguments and return as a Config object.
 
         Parameters
         ----------
@@ -348,10 +460,10 b' class ArgParseConfigLoader(CommandLineConfigLoader):'
           arguments from. If not given, the instance's self.argv attribute
           (given at construction time) is used."""
         self.clear()
-        if args is None:
-            args = self.argv
+        if argv is None:
+            argv = self.argv
         self._create_parser()
-        self._parse_args(args)
+        self._parse_args(argv)
         self._convert_to_config()
         return self.config
 

IPython/config/tests/test_configurable.py

@@ -22,10 +22,15 b' Authors:'
 
 from unittest import TestCase
 
-from IPython.config.configurable import Configurable, ConfigurableError
+from IPython.config.configurable import (
+    Configurable, 
+    SingletonConfigurable
+)
+
 from IPython.utils.traitlets import (
-    TraitError, Int, Float, Str
+    Int, Float, Str
 )
+
 from IPython.config.loader import Config
 
 
@@ -35,22 +40,29 b' from IPython.config.loader import Config'
 
 
 class MyConfigurable(Configurable):
-    a = Int(1, config=True)
-    b = Float(1.0, config=True)
+    a = Int(1, config=True, help="The integer a.")
+    b = Float(1.0, config=True, help="The integer b.")
     c = Str('no config')
 
 
+mc_help=u"""MyConfigurable options
+----------------------
+MyConfigurable.a : Int
+    The integer a.
+MyConfigurable.b : Float
+    The integer b."""
+
 class Foo(Configurable):
-    a = Int(0, config=True)
+    a = Int(0, config=True, help="The integer a.")
     b = Str('nope', config=True)
 
 
 class Bar(Foo):
-    b = Str('gotit', config=False)
-    c = Float(config=True)
+    b = Str('gotit', config=False, help="The string b.")
+    c = Float(config=True, help="The string c.")
 
 
-class TestConfigurableConfig(TestCase):
+class TestConfigurable(TestCase):
 
     def test_default(self):
         c1 = Configurable()
@@ -122,3 +134,31 b' class TestConfigurableConfig(TestCase):'
         self.assertEquals(c.a, 2)
         self.assertEquals(c.b, 'and')
         self.assertEquals(c.c, 20.0)
+
+    def test_help(self):
+        self.assertEquals(MyConfigurable.class_get_help(), mc_help)
+
+
+class TestSingletonConfigurable(TestCase):
+
+    def test_instance(self):
+        from IPython.config.configurable import SingletonConfigurable
+        class Foo(SingletonConfigurable): pass
+        self.assertEquals(Foo.initialized(), False)
+        foo = Foo.instance()
+        self.assertEquals(Foo.initialized(), True)
+        self.assertEquals(foo, Foo.instance())
+        self.assertEquals(SingletonConfigurable._instance, None)
+
+    def test_inheritance(self):
+        class Bar(SingletonConfigurable): pass
+        class Bam(Bar): pass
+        self.assertEquals(Bar.initialized(), False)
+        self.assertEquals(Bam.initialized(), False)
+        bam = Bam.instance()
+        bam == Bar.instance()
+        self.assertEquals(Bar.initialized(), True)
+        self.assertEquals(Bam.initialized(), True)
+        self.assertEquals(bam, Bam._instance)
+        self.assertEquals(bam, Bar._instance)
+        self.assertEquals(SingletonConfigurable._instance, None)

IPython/config/tests/test_loader.py

@@ -24,9 +24,12 b' import os'
 from tempfile import mkstemp
 from unittest import TestCase
 
+from IPython.utils.traitlets import Int, Unicode
+from IPython.config.configurable import Configurable
 from IPython.config.loader import (
     Config,
-    PyFileConfigLoader, 
+    PyFileConfigLoader,
+    KeyValueConfigLoader,
     ArgParseConfigLoader,
     ConfigError
 )
@@ -38,11 +41,11 b' from IPython.config.loader import ('
 
 pyfile = """
 c = get_config()
-c.a = 10
-c.b = 20
-c.Foo.Bar.value = 10
-c.Foo.Bam.value = range(10)
-c.D.C.value = 'hi there'
+c.a=10
+c.b=20
+c.Foo.Bar.value=10
+c.Foo.Bam.value=range(10)
+c.D.C.value='hi there'
 """
 
 class TestPyFileCL(TestCase):
@@ -109,6 +112,19 b' class TestArgParseCL(TestCase):'
         self.assertEquals(config.Global.bam, 'wow')
 
 
+class TestKeyValueCL(TestCase):
+
+    def test_basic(self):
+        cl = KeyValueConfigLoader()
+        argv = [s.strip('c.') for s in pyfile.split('\n')[2:-1]]
+        config = cl.load_config(argv)
+        self.assertEquals(config.a, 10)
+        self.assertEquals(config.b, 20)
+        self.assertEquals(config.Foo.Bar.value, 10)
+        self.assertEquals(config.Foo.Bam.value, range(10))
+        self.assertEquals(config.D.C.value, 'hi there')
+
+
 class TestConfig(TestCase):
 
     def test_setget(self):

IPython/core/interactiveshell.py

@@ -31,7 +31,7 b' import tempfile'
 import types
 from contextlib import nested
 
-from IPython.config.configurable import Configurable
+from IPython.config.configurable import SingletonConfigurable
 from IPython.core import debugger, oinspect
 from IPython.core import history as ipcorehist
 from IPython.core import page
@@ -132,9 +132,7 b' class SeparateStr(Str):'
         value = value.replace('\\n','\n')
         return super(SeparateStr, self).validate(obj, value)
 
-class MultipleInstanceError(Exception):
-    pass
-    
+
 class ReadlineNoRecord(object):
     """Context manager to execute some code, then reload readline history
     so that interactive input to the code doesn't appear when pressing up."""
@@ -181,25 +179,78 b' class ReadlineNoRecord(object):'
         return [ghi(x) for x in range(start, end)]
 
 
+_autocall_help = """
+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'.
+"""
+
 #-----------------------------------------------------------------------------
 # Main IPython class
 #-----------------------------------------------------------------------------
 
-class InteractiveShell(Configurable, Magic):
+class InteractiveShell(SingletonConfigurable, Magic):
     """An enhanced, interactive shell for Python."""
 
     _instance = None
-    autocall = Enum((0,1,2), default_value=1, config=True)
+
+    autocall = Enum((0,1,2), default_value=1, config=True, help=
+        """
+        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'.
+        """
+    )
     # TODO: remove all autoindent logic and put into frontends.
     # We can't do this yet because even runlines uses the autoindent.
-    autoindent = CBool(True, config=True)
-    automagic = CBool(True, config=True)
-    cache_size = Int(1000, config=True)
-    color_info = CBool(True, config=True)
+    autoindent = CBool(True, config=True, help=
+        """
+        Autoindent IPython code entered interactively.
+        """
+    )
+    automagic = CBool(True, config=True, help=
+        """
+        Enable magic commands to be called without the leading %.
+        """
+    )
+    cache_size = Int(1000, config=True, help=
+        """
+        Set the size of the output cache.  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
+        """
+    )
+    color_info = CBool(True, config=True, help=
+        """
+        Use colors for displaying information about objects. Because this
+        information is passed through a pager (like 'less'), and some pagers
+        get confused with color codes, this capability can be turned off.
+        """
+    )
     colors = CaselessStrEnum(('NoColor','LightBG','Linux'), 
                              default_value=get_default_colors(), config=True)
     debug = CBool(False, config=True)
-    deep_reload = CBool(False, config=True)
+    deep_reload = CBool(False, config=True, help=
+        """
+        Enable deep (recursive) reloading by default. 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().
+        """
+    )
     display_formatter = Instance(DisplayFormatter)
     displayhook_class = Type(DisplayHook)
     display_pub_class = Type(DisplayPublisher)
@@ -217,12 +268,28 b' class InteractiveShell(Configurable, Magic):'
     # interactive statements or whole blocks.
     input_splitter = Instance('IPython.core.inputsplitter.IPythonInputSplitter',
                               (), {})
-    logstart = CBool(False, config=True)
-    logfile = Unicode('', config=True)
-    logappend = Unicode('', config=True)
+    logstart = CBool(False, config=True, help=
+        """
+        Start logging to the default log file.
+        """
+    )
+    logfile = Unicode('', config=True, help=
+        """
+        The name of the logfile to use.
+        """
+    )
+    logappend = Unicode('', config=True, help=
+        """
+        Start logging to the given file in append mode.
+        """
+    )
     object_info_string_level = Enum((0,1,2), default_value=0,
                                     config=True)
-    pdb = CBool(False, config=True)
+    pdb = CBool(False, config=True, help=
+        """
+        Automatically call the pdb debugger after every exception.
+        """
+    )
 
     profile = Unicode('', config=True)
     prompt_in1 = Str('In [\\#]: ', config=True)
@@ -356,31 +423,6 b' class InteractiveShell(Configurable, Magic):'
         self.hooks.late_startup_hook()
         atexit.register(self.atexit_operations)
 
-    @classmethod
-    def instance(cls, *args, **kwargs):
-        """Returns a global InteractiveShell instance."""
-        if cls._instance is None:
-            inst = cls(*args, **kwargs)
-            # Now make sure that the instance will also be returned by
-            # the subclasses instance attribute.
-            for subclass in cls.mro():
-                if issubclass(cls, subclass) and \
-                       issubclass(subclass, InteractiveShell):
-                    subclass._instance = inst
-                else:
-                    break
-        if isinstance(cls._instance, cls):
-            return cls._instance
-        else:
-            raise MultipleInstanceError(
-                'Multiple incompatible subclass instances of '
-                'InteractiveShell are being created.'
-            )
-
-    @classmethod
-    def initialized(cls):
-        return hasattr(cls, "_instance")
-
     def get_ipython(self):
         """Return the currently running IPython instance."""
         return self

IPython/utils/tests/test_traitlets.py

@@ -366,6 +366,7 b' class TestHasTraits(TestCase):'
             f = Float
         a = A()
         self.assertEquals(a.trait_names(),['i','f'])
+        self.assertEquals(A.class_trait_names(),['i','f'])
 
     def test_trait_metadata(self):
         class A(HasTraits):
@@ -379,6 +380,7 b' class TestHasTraits(TestCase):'
             f = Float
         a = A()
         self.assertEquals(a.traits(), dict(i=A.i, f=A.f))
+        self.assertEquals(A.class_traits(), dict(i=A.i, f=A.f))
 
     def test_traits_metadata(self):
         class A(HasTraits):

IPython/utils/traitlets.py

@@ -515,6 +515,48 b' class HasTraits(object):'
             for n in names:
                 self._add_notifiers(handler, n)
 
+    @classmethod
+    def class_trait_names(cls, **metadata):
+        """Get a list of all the names of this classes traits.
+
+        This method is just like the :meth:`trait_names` method, but is unbound.
+        """
+        return cls.class_traits(**metadata).keys()
+
+    @classmethod
+    def class_traits(cls, **metadata):
+        """Get a list of all the traits of this class.
+
+        This method is just like the :meth:`traits` method, but is unbound.
+
+        The TraitTypes returned don't know anything about the values
+        that the various HasTrait's instances are holding.
+
+        This follows the same algorithm as traits does and does not allow
+        for any simple way of specifying merely that a metadata name
+        exists, but has any value.  This is because get_metadata returns
+        None if a metadata key doesn't exist.
+        """
+        traits = dict([memb for memb in getmembers(cls) if \
+                     isinstance(memb[1], TraitType)])
+
+        if len(metadata) == 0:
+            return traits
+
+        for meta_name, meta_eval in metadata.items():
+            if type(meta_eval) is not FunctionType:
+                metadata[meta_name] = _SimpleTest(meta_eval)
+
+        result = {}
+        for name, trait in traits.items():
+            for meta_name, meta_eval in metadata.items():
+                if not meta_eval(trait.get_metadata(meta_name)):
+                    break
+            else:
+                result[name] = trait
+
+        return result
+
     def trait_names(self, **metadata):
         """Get a list of all the names of this classes traits."""
         return self.traits(**metadata).keys()