Writing your first configglue-enabled application

This is a minimalistic step-by-step guide on how to start using configglue to manage configuration settings for your application.

Jump right in

Most of the time the code needed to make your application work with configglue will look like the following snippet, so let’s look at it in detail:

def main(config, opts):
    # do something
    values = config.values('__main__')
    for opt in ('foo', 'bar'):
        option = config.schema.section('__main__').option(opt)
        value = values.get(opt)
        if value != option.default:
            print "%s option has been configured with value: %s" % (opt,
                value)
        else:
            print "%s option has default value: %s" % (opt, option.default)

if __name__ == '__main__':
    from configglue import schema

    # create the schema
    class MySchema(schema.Schema):
        foo = schema.IntOption()
        bar = schema.BoolOption()

    # read the configuration files
    scp = schema.SchemaConfigParser(MySchema())
    scp.read(['config.ini'])

    # support command-line integration
    op, opts, args = schema.schemaconfigglue(scp)

    # validate the config (after taking into account any command-line
    # provided options
    is_valid, reasons = scp.is_valid(report=True)
    if not is_valid:
        op.error(reasons[0])

    # run
    main(scp, opts)

Let’s start at the top.

You’ll probably have a main function that you’ll be calling to get your application started.

def main(config, opts):
    # do something
    ...

if __name__ == '__main__':
    ...
    # run
    main(scp, opts)

So, for configglue to deliver it’s awesomeness, all the magic has to happen before calling your main function.

The general structure is:

1. Create a schema for your configuration

   class MySchema(schema.Schema):
       foo = schema.IntOption()
       bar = schema.BoolOption()
   

2. Create a parser for that schema

   scp = schema.SchemaConfigParser(MySchema())
   

3. Read the configuration files (to get the statically defined configuration values)

   scp.read(['config.ini'])
   

4. (Optional) Weave in command-line integration support (so that configuration options can be overridden via command-line)

   op, opts, args = schema.schemaconfigglue(scp)
   

5. (Optional) Validate the effective configuration (to capture any configuration issues)

   is_valid, reasons = scp.is_valid(report=True)
   if not is_valid:
       op.error(reasons[0])
   

Since this code will be structured the same for any configglue-enabled project you do, there is also a utility function you can use to avoid repeating yourself.

When using that function (see configglue.glue.configglue()), this code would look like:

def main(config, opts):
    # do something
    values = config.values('__main__')
    for opt in ('foo', 'bar'):
        option = config.schema.section('__main__').option(opt)
        value = values.get(opt)
        if value != option.default:
            print "%s option has been configured with value: %s" % (opt,
                value)
        else:
            print "%s option has default value: %s" % (opt, option.default)

if __name__ == '__main__':
    from configglue import schema
    from configglue.glue import configglue

    # create the schema
    class MySchema(schema.Schema):
        foo = schema.IntOption()
        bar = schema.BoolOption()

    # glue everything together
    glue = configglue(MySchema, ['config.ini'])

    # run
    main(glue.schema_parser, glue.options)

Test it

To test our configglue support, let’s try out different use cases.

1. Default values

   $ python app.py
   foo option has default value: 0
   bar option has default value: False

2. Config file

   Write the following content to a file called config.ini:

   [__main__]
   bar = true
   

   and then run

   $ python app.py
   foo option has default value: 0
   bar option has been configured with value: True

3. Command-line integration

   $ python app.py --foo=2
   foo option has been configured with value: 2
   bar option has been configured with value: True

   Note

   This output is assuming you still have the config.ini file you created during the previous use case.

Profit!

That’s it! Your application now uses configglue to manage it’s configuration. Congratulations!