API Reference

Parse configuration values from files, the environment, and elsewhere all in one place.

exception easy_config.ConfigValueCoercionError

Raised when a configuration value cannot be converted to the proper type.

Example: field type is int and the value is None or 'apple'.

__weakref__

list of weak references to the object (if defined)

class easy_config.EasyConfig(**_kwargs)

The parent class of all configuration classes.

__init__(**_kwargs)

Do not instantiate the base class.

TypeError is raised instead of NotImplementedError to prevent IDEs (namely: PyCharm) from complaining that subclasses have not implemented all abstract methods. See https://github.com/scolby33/easy_config/issues/19

Raises:TypeError – always; this class must be subclassed Return type:None

classmethod _read_file(config_file)

Read configuration values from a file.

This method parses ConfigParser-style INI files. To parse other formats, subclass EasyConfig and override this method.

Parameters:config_file (Union[str, Path, Iterable[str]]) – the file from which configuration will be read. Note that this can be an Iterable[str], which includes open files and TextIO objects. Return type:Dict[str, Any] Returns:a mapping from string configuration value names to their values Raises:ConfigValueCoercionError – when an error occurs calling the type constructor on an input value

classmethod _read_environment()

Read configuration values from the environment.

Configuration values are looked up in the environment by the concatenation of the value name and the NAME class variable with an underscore separator.

For example, the configuration value “number” for an instance with the NAME “myprogram” will be read from the environment variable “MYPROGRAM_NUMBER”.

Return type:Dict[str, Any] Returns:a mapping from string configuration value names to their values Raises:ConfigValueCoercionError – when an error occurs calling the type constructor on an input value

classmethod _read_dict(d)

Read configuration values from a passed-in mapping.

Configuration values are extracted from the input mapping. Only keys in the mapping that are valid configuration values names are returned, others are ignored.

Parameters:d (Mapping[str, Any]) – the input mapping of string configuration value names to their values Return type:Dict[str, Any] Returns:a mapping from string configuration value names to their values Raises:ConfigValueCoercionError – when an error occurs calling the type constructor on an input value

classmethod load(_additional_files=None, *, _parse_files=True, _parse_environment=True, _lookup_config_envvar=None, **kwargs)

Load configuration values from multiple locations and create a new instance of the configuration class with those values.

Values are read in the following order. The last value read takes priority.

1. values from the files listed in the FILES class variable, in order
2. values from files passed in the additional_files parameter, in order
3. values from the file specified by the config file specified by the environment variable _lookup_config_envvar
4. values from the environment
5. values passed as keyword arguments to this method (useful for values specified on the command line)

Parameters:

• _additional_files (Optional[Iterable[Union[str, Path, Textio]]]) – files to be parsed in addition to those named in the FILES class variable; always parsed, no matter the value of the parse_files flag
• _parse_files (bool) – whether to parse files from the FILES class variable
• _parse_environment (bool) – whether to parse the environment for configuration values
• _lookup_config_envvar (Optional[str]) – the environment variable that contains the config file location. Like the loading from the environment, this value will be uppercased and appended to the program name. For example, the _lookup_config_envvar “config” for an instance with the NAME “myprogram” will result in a search for the environment variable “MYPROGRAM_CONFIG” for the path to the configuration file.
• kwargs (Any) – additional keyword arguments are passed through unchanged to the final configuration object

Return type:

~EasyConfigOrSubclass

Returns:

an instance of the configuration class loaded with the parsed values

classmethod _load_helper(_additional_files=None, *, _parse_files=True, _parse_environment=True, _lookup_config_envvar=None, **kwargs)

Help load the dictionaries in .load().

Return type:Generator[Dict[str, Any], None, None]

dump(fp)

Serialize all current configuration values to fp as a ConfigParser-style INI.

Values will be placed in the section corresponding to the class value NAME.

Parameters:fp (Textio) – a write()-supporting file-like object Return type:None

__weakref__

list of weak references to the object (if defined)