From 4a3f8d5e3f9b3fb5c9a066387407662d1ebe9d63 2011-04-24 00:42:02 From: Brian Granger Date: 2011-04-24 00:42:02 Subject: [PATCH] Adding more documentation to config.application related files. --- diff --git a/IPython/config/application.py b/IPython/config/application.py index 48e5aa2..2dab68b 100644 --- a/IPython/config/application.py +++ b/IPython/config/application.py @@ -36,6 +36,7 @@ from IPython.config.loader import ( 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 @@ -98,6 +99,7 @@ class Application(SingletonConfigurable): 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. diff --git a/IPython/config/tests/test_application.py b/IPython/config/tests/test_application.py new file mode 100644 index 0000000..2053d99 --- /dev/null +++ b/IPython/config/tests/test_application.py @@ -0,0 +1,90 @@ +""" +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) + diff --git a/docs/examples/core/appconfig.py b/docs/examples/core/appconfig.py index f682717..44bb74a 100644 --- a/docs/examples/core/appconfig.py +++ b/docs/examples/core/appconfig.py @@ -7,6 +7,27 @@ system works. The main classes are: * 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 @@ -17,7 +38,11 @@ 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.") @@ -39,9 +64,11 @@ class MyApp(Application): 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)