Adding more documentation to config.application related files.

IPython/config/tests/test_application.py

@@ -0,0 +1,90 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
+)
+
+#-----------------------------------------------------------------------------
+# Code
+#-----------------------------------------------------------------------------
+
+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="enabled", help="Enable bar.")
+
+
+class MyApp(Application):
+
+    app_name = Unicode(u'myapp')
+    running = Bool(False, config=True, shortname="running",
+                   help="Is the app running?")
+    classes = List([Bar, Foo])
+    config_file = Unicode(u'', config=True, shortname="config_file",
+                   help="Load this config file")
+
+    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)
+

IPython/config/application.py

@@ -1,132 +1,134 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.utils.traitlets import (
     Unicode, List, Int, Enum
 )
 from IPython.config.loader import (
     KeyValueConfigLoader, PyFileConfigLoader
 )
 
 #-----------------------------------------------------------------------------
 # 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.')
 
     # 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')
 
     # The log level for the application
     log_level = Enum((0,10,20,30,40,50), default_value=logging.WARN,
                      config=True, shortname="log_level",
                      help="Set the log level (0,10,20,30,40,50).")
 
     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__)
         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_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):
+        """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 '--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)
 

docs/examples/core/appconfig.py

@@ -1,61 +1,88 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
 )
 
+
 class Foo(Configurable):
+    """A class that has configurable, typed attributes.
+
+    """
 
     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="enabled", help="Enable bar.")
 
 
 class MyApp(Application):
 
     app_name = Unicode(u'myapp')
     running = Bool(False, config=True, shortname="running",
                    help="Is the app running?")
     classes = List([Bar, Foo])
     config_file = Unicode(u'', config=True, shortname="config_file",
                    help="Load this config file")
 
     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()