Configuration with a single block

This example shows how to set up a simple example with a few options and only one block. In what follows you should assume that all commands are being performed sequentially in one python session

First the set of allowed options must be specified:

from configblock.configblock import ConfigBlock

cfg = ConfigBlock()
# Add a simple option
cfg.add_option("Text", default="Hello World!", help="A sample message")

Options can have a type provided. This mirrors the same idea in the argparse module where type is a function that gets called on the provided value. Here int is used to convert the provided value to an integer.

cfg.add_option("Integer", default=10, type=int, help="An integer value")

Any option without a default set will be treated as required. It is an error not to provide this.

cfg.add_option("Required", help="A required option")

Default values can also be function-like objects. These will be called with the ConfigBlock as an argument when the value is accessed.

from operator import itemgetter
cfg.add_option(
    "Dynamic",
    default=itemgetter("Text"),
    help="An example whose default copies the value in 'Text'",
)

An option whose default value is None can be made optional by setting required to False

cfg.add_option("Optional", required=False, help="An optional value")

Options can also be restricted to be one of a number of values. Attempting to set a value not in the list gives an error.

cfg.add_option(
    "Limited",
    type=int,
    choices=(1, 2, 5),
    help="An integer with a limited number of possible values",
)

Options can also specify a custom validator that either returns False on a bad value or raises an exception. The validator receives the value after it has been passed through the type function. Here this validator requires that the provided value is less than 10.

cfg.add_option(
    "RangeChecked",
    type=int,
    validator=lambda x: x < 10,
    help="An integer that must be less than 10"
)

Validators will also be run over default values.

cfg.add_option(
    "ValidateDefault",
    default=itemgetter("Integer"),
    validator=lambda x: x > 100,
)

Individual options are set and accessed using standard dictionary access semantics. If no value has been set then the default is returned.

>>> cfg["Text"]
"Hello World!"
>>> cfg["Text"] = "Goodbye!"
>>> cfg["Text"]
"Goodbye!"

Deleting an option removes any value set, not the option itself

>>> del cfg["Text"]
>>> cfg["Text"]
"Hello World!"

Setting the Integer option will convert the supplied value.

>>> cfg["Integer"] = "3"
>>> cfg["Integer"]
3
>>> cfg["Integer"] = 55
>>> cfg["Integer"]
55
>>> cfg["Integer"] = 3.14
>>> cfg["Integer"]
3
>>> cfg["Integer"] = "Not an integer"
ValueError: invalid literal for int() with base 10: 'Not an integer'

Accessing an unset option that is required gives a KeyError

>>> cfg["Required"]
KeyError: 'Required'

An option which has a function as its default will have that function called each time it is accessed until the value is set

>>> cfg["Dynamic"]
"Hello World!"
>>> cfg["Text"] = "Something else"
>>> cfg["Dynamic"]
"Something else"
>>> cfg["Dynamic"] = "Goodbye"
>>> del cfg["Text"]
>>> cfg["Dynamic"]
"Goodbye"