Created config.application and updated Configurable.

IPython/config/application.py

@@ -0,0 +1,108 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 sys
+
+from IPython.config.configurable import Configurable
+from IPython.utils.traitlets import (
+    Unicode, List
+)
+from IPython.config.loader import (
+    KeyValueConfigLoader, PyFileConfigLoader
+)
+
+#-----------------------------------------------------------------------------
+# Application class
+#-----------------------------------------------------------------------------
+
+
+class Application(Configurable):
+
+    # 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.')
+
+    # A sequence of Configurable subclasses whose config=True attributes will
+    # be exposed at the command line (shortnames and help).
+    classes = List([])
+
+    # The version string of this application.
+    version = Unicode(u'0.0')
+
+    def __init__(self, **kwargs):
+        Configurable.__init__(self, **kwargs)
+        # Add my class to self.classes so my attributes appear in command line
+        # options.
+        self.classes.insert(0, self.__class__)
+
+    def print_help(self):
+        """Print the help for each Configurable class in self.classes."""
+        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):
+        # 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."""
+        if argv is None:
+            argv = sys.argv[1:]
+
+        if '-h' in argv or '--h' 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, classes=self.classes)
+        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/configurable.py

@@ -1,170 +1,173 b''
 #!/usr/bin/env python
 # encoding: utf-8
 """
 A base class for objects that are configurable.
 
 Authors:
 
 * Brian Granger
 * Fernando Perez
 """
 
 #-----------------------------------------------------------------------------
 #  Copyright (C) 2008-2010  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 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
 
 
 #-----------------------------------------------------------------------------
 # Helper classes for Configurables
 #-----------------------------------------------------------------------------
 
 
 class ConfigurableError(Exception):
     pass
 
 
 #-----------------------------------------------------------------------------
 # Configurable implementation
 #-----------------------------------------------------------------------------
 
 
 class Configurable(HasTraits):
 
     config = Instance(Config,(),{})
     created = None
 
     def __init__(self, **kwargs):
         """Create a conigurable given a config config.
 
         Parameters
         ----------
         config : Config
             If this is empty, default values are used. If config is a 
             :class:`Config` instance, it will be used to configure the
             instance.
         
         Notes
         -----
         Subclasses of Configurable must call the :meth:`__init__` method of
         :class:`Configurable` *before* doing anything else and using 
         :func:`super`::
         
             class MyConfigurable(Configurable):
                 def __init__(self, config=None):
                     super(MyConfigurable, self).__init__(config)
                     # Then any other code you need to finish initialization.
 
         This ensures that instances will be configured properly.
         """
         config = kwargs.pop('config', None)
         if config is not None:
             # We used to deepcopy, but for now we are trying to just save
             # by reference.  This *could* have side effects as all components
             # will share config. In fact, I did find such a side effect in
             # _config_changed below. If a config attribute value was a mutable type
             # all instances of a component were getting the same copy, effectively
             # making that a class attribute.
             # self.config = deepcopy(config)
             self.config = config
         # This should go second so individual keyword arguments override 
         # the values in config.
         super(Configurable, self).__init__(**kwargs)
         self.created = datetime.datetime.now()
 
     #-------------------------------------------------------------------------
     # Static trait notifiations
     #-------------------------------------------------------------------------
 
     def _config_changed(self, name, old, new):
         """Update all the class traits having ``config=True`` as metadata.
 
         For any class trait with a ``config`` metadata attribute that is
         ``True``, we update the trait with the value of the corresponding
         config entry.
         """
         # Get all traits with a config metadata entry that is True
         traits = self.traits(config=True)
 
         # We auto-load config section for this class as well as any parent
         # classes that are Configurable subclasses.  This starts with Configurable
         # and works down the mro loading the config for each section.
         section_names = [cls.__name__ for cls in \
             reversed(self.__class__.__mro__) if 
             issubclass(cls, Configurable) and issubclass(self.__class__, cls)]
 
         for sname in section_names:
             # Don't do a blind getattr as that would cause the config to 
             # dynamically create the section with name self.__class__.__name__.
             if new._has_section(sname):
                 my_config = new[sname]
                 for k, v in traits.iteritems():
                     # Don't allow traitlets with config=True to start with
                     # uppercase.  Otherwise, they are confused with Config
                     # subsections.  But, developers shouldn't have uppercase
                     # attributes anyways! (PEP 6)
                     if k[0].upper()==k[0] and not k.startswith('_'):
                         raise ConfigurableError('Configurable traitlets with '
                         'config=True must start with a lowercase so they are '
                         'not confused with Config subsections: %s.%s' % \
                         (self.__class__.__name__, k))
                     try:
                         # Here we grab the value from the config
                         # If k has the naming convention of a config
                         # section, it will be auto created.
                         config_value = my_config[k]
                     except KeyError:
                         pass
                     else:
                         # print "Setting %s.%s from %s.%s=%r" % \
                         #     (self.__class__.__name__,k,sname,k,config_value)
                         # We have to do a deepcopy here if we don't deepcopy the entire
                         # config object. If we don't, a mutable config_value will be
                         # shared by all instances, effectively making it a class attribute.
                         setattr(self, k, deepcopy(config_value))
 
     @classmethod
     def class_get_shortnames(cls):
         """Return the shortname to fullname dict for config=True traits."""
         cls_traits = cls.class_traits(config=True)
         shortnames = {}
         for k, v in cls_traits.items():
             shortname = v.get_metadata('shortname')
             if shortname is not None:
                 longname = cls.__name__ + '.' + k
                 shortnames[shortname] = longname
         return shortnames
 
     @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('%s options' % cls.__name__)
-        final_help.append(len(final_help[0])*'-')
+        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')
-            final_help.append(k + " : " + v.__class__.__name__)
+            shortname = v.get_metadata('shortname')
+            header = "%s.%s : %s" % (cls.__name__, k, v.__class__.__name__)
+            if shortname is not None:
+                header += " (shortname=" + shortname + ")"
+            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()
 
             
  No newline at end of file

docs/examples/core/appconfig.py

@@ -1,55 +1,39 b''
 import sys
 
 from IPython.config.configurable import Configurable
+from IPython.config.application import Application
 from IPython.utils.traitlets import (
     Bool, Unicode, Int, Float, List
 )
-from IPython.config.loader import KeyValueConfigLoader
 
 class Foo(Configurable):
 
     i = Int(0, config=True, shortname='i', help="The integer i.")
     j = Int(1, config=True, shortname='j', help="The integer j.")
     name = Unicode(u'Brian', config=True, shortname='name', help="First name.")
 
 
 class Bar(Configurable):
 
     enabled = Bool(True, config=True, shortname="bar-enabled", help="Enable bar.")
 
 
-class MyApp(Configurable):
+class MyApp(Application):
 
-    app_name = Unicode(u'myapp', config=True, shortname="myapp", help="The app name.")
+    app_name = Unicode(u'myapp')
     running = Bool(False, config=True, shortname="running", help="Is the app running?")
     classes = List([Bar, Foo])
-
-    def __init__(self, **kwargs):
-        Configurable.__init__(self, **kwargs)
-        self.classes.insert(0, self.__class__)
-
-    def print_help(self):
-        for cls in self.classes:
-            cls.class_print_help()
-            print
-
-    def parse_command_line(self, argv=None):
-        if argv is None:
-            argv = sys.argv[1:]
-        if '-h' in argv or '--h' in argv:
-            self.print_help()
-            sys.exit(1)
-        loader = KeyValueConfigLoader(argv=argv, classes=self.classes)
-        config = loader.load_config()
-        self.config = config
+    config_file = Unicode(u'', config=True, shortname="config-file", help="Load this config file")
 
 
 def main():
     app = MyApp()
     app.parse_command_line()
+    if app.config_file:
+        app.load_config_file(app.config_file)
     print "app.config:"
     print app.config
 
 
 if __name__ == "__main__":
     main()