API documentation¶
-
class
confloader.
ConfDict
(*args, **kwargs)¶ Dictionary subclass that is used to hold the parsed configuration options.
ConfDict
is instantiated the same way as dicts. For this reason, the paths to configuation files and similar are not passed to the constructor. Instead, you should use thefrom_file()
classmethod.Because this class is a dictionary, you can use the standard
dict
API to access and modify the keys. There is a minor difference when accessing key values, though. When using the subscript notation,ConfigurationFormatError
is raised instead ofKeyError
when the key is missing.-
exception
ConfigurationError
¶ Raised when application is not configured correctly.
-
exception
ConfDict.
ConfigurationFormatError
(keyerr)¶ Raised when configuration file is malformed.
-
ConfDict.
configure
(path, skip_clean=False, noextend=False)¶ Configure the
ConfDict
instance for processing.The
path
is a path to the configuration file.skip_clean
parameter is a boolean flag that suppresses type conversion during parsing.noextend
flag suppresses list extension.
-
classmethod
ConfDict.
from_file
(path, skip_clean=False, noextend=False, defaults={})¶ Load the values from the specified file. The
skip_clean
flag is used to suppress type conversion.noextend
flag suppresses list extension.You may also specify default options using the
defaults
argument. This argument should be a dict. Values specified in this dict are overridden by the values present in the configuration file.
-
ConfDict.
get_option
(section, name, default=None)¶ Returns a single configuration option that matches the given section and option names. Optional default value can be specified using the
default
parameter, and this value is returned when the option is not found.As with
get_section()
method, this method operates on the parsed configuration file rather than dictionary data.
-
ConfDict.
get_section
(name)¶ Returns an iterable containing options for a given section. This method does not return the dict values, but instead uses the underlying parser object to retrieve the values from the parsed configuration file.
-
ConfDict.
import_from_file
(path, as_defaults=False, ignore_missing=False)¶ Imports additional options from specified file. The
as_default
flag can be used to cause the options to only be imported if they are not already present. Theignore_missing
suppresses theConfigurationError
exception when the specified file is missing.
-
ConfDict.
load
()¶ Parses and loads the configuration data. This method will trigger a sequence of operations:
- initialize the parser, and load and parse the configuration file
- check the configuration file
- perform preprocessing (check for references to other files)
- process the sections
- process any includes or extensions
Any problems with the referenced defaults and includes will propagate to this call.
Note
Using this method for reloading the configuration is not recommended. Instead, create a new instance using the
from_file()
method.
-
ConfDict.
sections
¶ Returns an iterable containing the names of sections. This method uses the underlying parser object and does not work with the dict values.
-
exception
-
exception
confloader.
ConfigurationError
¶ Raised when application is not configured correctly.
-
exception
confloader.
ConfigurationFormatError
(keyerr)¶ Raised when configuration file is malformed.
-
confloader.
extend_key
(d, key, val)¶ Extends a dictionary key with a specified iterable. If the key does not exist, it is assigned a list before extending. If the key exists, but maps to a non-list value, the key value is convereted to a list before being extended.
-
confloader.
get_compound_key
(section, key)¶ Return the key that will be used to look up configuration options. Except for the global keys, the compoint key is in
<section>.<option>
format.
-
confloader.
get_config_path
(default=None)¶ Attempt to obtain and return a path to configuration file specified by
--conf
command line argument, and fall back on specified default path. Default value isNone
.
-
confloader.
make_list
(val)¶ If the value is not a list, it is converted to a list. Iterables like tuple and list itself are converted to lists, whereas strings, integers, and other values are converted to a list whose sole item is the original value.
-
confloader.
parse_key
(section, key)¶ Given section name and option name (key), return a compound key and a flag that is
True
if the option marks an extension.
-
confloader.
parse_size
(size)¶ Parses size with B, KB, MB, or GB suffix and returns in size bytes. The suffix is not metric but based on powers of 1024. The suffix is also case-insensitive.
-
confloader.
parse_value
(val)¶ Detect value type and coerce to appropriate Python type. The input must be a string and the value’s type is derived based on it’s formatting. The following types are supported:
- boolean (‘yes’, ‘no’, ‘true’, ‘false’, case-insensitive)
- None (‘null’, ‘none’, case-insensitive)
- integer (any number of digits, optionally prefixed with minus sign)
- float (digits with floating point, optionally prefix with minus sign)
- byte sizes (same as float, but with KB, MB, or GB suffix)
- lists (any value that sarts with a newline)
Other values are returned as is.