Writing configglue-enabled applications¶
By inheriting from App, your application will reap the benefits of being able to
Read configuration files from standard locations¶
The configglue-enabled app will automatically follow the XDG standards for looking up configuration files. For example, if your application is named myapp, the following locations will be searched for configuration values:
/etc/xdg/myapp/myapp.cfg /home/<user>/.config/myapp/myapp.cfg ./local.cfg
Support plugins for extending your application¶
The class Plugin will allow you to write plugins for your application so that each plugin can have it’s own configglue-based configuration.
Each plugin registered with the application will have it’s own schema and configuration files, which will be included during validation. If the plugin is named myplugin, the following additional locations will be searched for configuration values:
Plugins need to be registered with the application manually for the time being. For doing so, just call register(), like:
class FooSchema(Schema): bar = IntOption() class Foo(Plugin): enabled = True schema = FooSchema myapp = App(name='myapp') myapp.plugins.register(Foo)
This example will register a Foo plugin which will be enabled by default.
Plugins can be enabled/disabled on demand, by calling the respective method
>>> myapp.plugins.enable(Foo) >>> print myapp.plugins.enabled [<class 'Foo'>] >>> myapp.plugins.disable(Foo) >>> print myapp.plugins.enabled 
The list of available plugins can be retrieved like
>>> print myapp.plugins.available [<class 'Foo'>]
Nicely integrate with the command line¶
By extending the App class, your program automatically has nice command line integration support built-in.
In order to show a help message, with information about each option your program supports, you can invoke it like:
python myapp.py --help
and it will output something similar to
Usage: myapp.py [options] Options: -h, --help show this help message and exit --validate validate configuration
Validating the configuration¶
If invoked with the –validate option, the configuration will be validated, producing one of two possible outcomes.
If no errors are found in the configuration, there will be no output, and your program will exit with a successful status code (0).
If errors are found during validation, those will be shown on the standard output, and your program will exit with an error status code (1).
Customizing the supported options¶
If you want to customize the options your program will support in the command line, beyond those already included by introspecting the schema, you can do so by initializing your application with an instance of optparse.OptionParser.
For example, imagine your application code looks like:
class MySchema(schema.Schema): foo = schema.IntOption() parser = OptionParser() parser.add_option('-b', '--bar') app = app.App(MySchema, parser=parser)
when invoking the help you’d get
Usage: myapp.py [options] Options: -h, --help show this help message and exit -b BAR, --bar=BAR --foo=FOO
If you override the option parser, you will not get the default options set. You will have to include them yourself, if so desired.
In order to trigger configuration validation, the only requirement is that the option parser includes a boolean option called validate.