Class ConfigItem

source code

object --+
         |
        ConfigItem

Known Subclasses:

• BooleanConfigItem
• , BytestringConfigItem
• , FloatConfigItem
• , IntConfigItem
• , StringConfigItem

A description of a configuration item including methods to parse and unparse them.

This class is an abstract base class for options with real syntax (_parse and _unparse methods).

ConfigItems have a section and a name (as in configparser), a value (that defaults to default), an origin (which is "default", if the value has not been changed and otherwise can be freely used by clients), and a description. The origin is important for distinguishing what to save.

You need to define the _parse and _unparse methods in deriving classes. The _parse methods must take a byte string (the encoding has to be utf-8) and return anything or raise ParseErrors (with a sensible description of the problem) if there is a problem with the input; the must not raise other exceptions when passed a string (but may do anything when passed something else. _unparse methods must not raise exceptions, take a value as returned by parse (nothing else must be passed in) and return a string that _parse would parse into this value.

Thus, the set method *only* takes strings as values. To set parsed values, assign to value directly. However, _unparse methods are not required to cope with any crazy stuff you enter in this way, and thus you suddenly may receive all kinds of funny exceptions when serializing a Configuration.

Inheriting classes need to specify a class attribute default that kicks in when no default has been specified during construction. These must be strings parseable by _parse.

Finally, you should provide a typedesc class attribute, a description of the type intended for human consumption. See the documentation functions below to get an idea how the would be shown.