Cement core config module.

class cement.core.config.CementConfigHandler(*args, **kw)

Bases: cement.core.handler.CementBaseHandler

Base class that all Config Handlers should sub-class from.

class Meta

Handler meta-data (can be passed as keyword arguments to the parent class).


The interface that this handler implements.

alias of IConfig

label = None

The string identifier of the implementation.


Parse a configuration file at file_path and store it. This function must be provided by the handler implementation (that is sub-classing this).

Parameters:file_path – The file system path to the configuration file.
Returns:True if file was read properly, False otherwise
Return type:boolean

Ensure we are using the absolute/expanded path to file_path, and then call _parse_file to parse config file settings from it, overwriting existing config settings. If the file does not exist, returns False.

Developers sub-classing from here should generally override _parse_file which handles just the parsing of the file and leaving this function to wrap any checks/logging/etc.

Parameters:file_path – The file system path to the configuration file.
class cement.core.config.IConfig

Bases: cement.core.interface.Interface

This class defines the Config Handler Interface. Classes that implement this handler must provide the methods and attributes defined below.

All implementations must provide sane ‘default’ functionality when instantiated with no arguments. Meaning, it can and should accept optional parameters that alter how it functions, but can not require any parameters. When the framework first initializes handlers it does not pass anything too them, though a handler can be instantiated first (with or without parameters) and then passed to ‘CementApp()’ already instantiated.

Implementations do not subclass from interfaces.


from cement.core import config

class MyConfigHandler(config.CementConfigHandler):
    class Meta:
        interface = config.IConfig
        label = 'my_config_handler'
class IMeta

Interface meta-data.

label = 'config'

The string identifier of the interface.


The validator function.


The _setup function is called during application initialization and must ‘setup’ the handler object making it ready for the framework or the application to make further calls to it.

Parameters:app_obj – The application object.

Add a new section if it doesn’t exist.

Parameters:section – The [section] label to create.

Return a configuration value based on [section][key]. The return value type is unknown.

  • section – The [section] of the configuration to pull key value from.
  • key – The configuration key to get the value from.

The value of the key in section.

Return type:



Return a dict of configuration parameters for [section].

Parameters:section – The config [section] to generate a dict from (using that section keys).
Returns:A dictionary of the config section.
Return type:dict

Return a list of configuration sections. These are designated by a [block] label in a config file.

Returns:A list of config sections.
Return type:list

Returns whether or not the section exists.

Parameters:section – The section to test for.

Return a list of configuration keys from section.

Parameters:section – The config [section] to pull keys from.
Returns:A list of keys in section.
Return type:list

Merges a dict object into the configuration.

  • dict_obj – The dictionary to merge into the config
  • override – Boolean. Whether to override existing values. Default: True



Parse config file settings from file_path. Returns True if the file existed, and was parsed successfully. Returns False otherwise.

Parameters:file_path – The path to the config file to parse.
Returns:True if the file was parsed, False otherwise.
Return type:boolean
set(key, value)

Set a configuration value based at [section][key].

  • section – The [section] of the configuration to pull key value from.
  • key – The configuration key to set the value at.
  • value – The value to set.


cement.core.config.config_validator(klass, obj)

Validates a handler implementation against the IConfig interface.