API

Functions to interact with config files

econf.read_file(file_name: str | bytes, delim: str | bytes, comment: str | bytes) → EconfFile

Read a config file and write the key-value pairs into a keyfile object

Parameters:

file_name – absolute path of file to be parsed
delim – delimiter of a key/value e.g. ‘=’
comment – string that defines the start of a comment e.g. ‘#’

Returns:

Key-Value storage object

econf.read_file_with_callback(file_name: str | bytes, delim: str | bytes, comment: str | bytes, callback: Callable[[any], bool], callback_data: any) → EconfFile

Read a config file and write the key-value pairs into a keyfile object

A user defined function will be called in order e.g. to check the correct file permissions. If the function returns False the parsing will be aborted and an Exception will be raised

Parameters:

file_name – absolute path of file to be parsed
delim – delimiter of a key/value e.g. ‘=’
comment – string that defines the start of a comment e.g. ‘#’
callback – User defined function which will be called and returns a boolean
callback_data – argument to be give to the callback function

Returns:

Key-Value storage object

econf.new_key_file(delim: str | bytes, comment: str | bytes) → EconfFile

Create a new empty keyfile

Parameters:

delim – delimiter of a key/value e.g. ‘=’
comment – string that defines the start of a comment e.g. ‘#’

Returns:

created EconfFile object

econf.new_ini_file() → EconfFile

Create a new empty keyfile with delimiter ‘=’ and comment ‘#’

Returns:: created EconfFile object

econf.merge_files(usr_file: EconfFile, etc_file: EconfFile) → EconfFile

Merge the content of 2 keyfile objects

Parameters:

usr_file – first EconfFile object
etc_file – second EconfFile object

Returns:

merged EconfFile object

Read configuration from the first found config file and merge with snippets from conf.d/ directory

e.g. searches /usr/etc/ and /etc/ for an example.conf file and merges it with the snippets in either /usr/etc/example.conf.d/ or /etc/example.conf.d

Parameters:

usr_conf_dir – absolute path of the first directory to be searched
etc_conf_dir – absolute path of the second directory to be searched
project_name – basename of the configuration file
config_suffix – suffix of the configuration file
delim – delimiter of a key/value e.g. ‘=’
comment – string that defines the start of a comment e.g. ‘#’

Returns:

merged EconfFile object

Read configuration from the first found config file and merge with snippets from conf.d/ directory

For every file a user defined function will be called in order e.g. to check the correct file permissions. If the function returns False the parsing will be aborted and an Exception will be raised

e.g. searches /usr/etc/ and /etc/ for an example.conf file and merges it with the snippets in either /usr/etc/example.conf.d/ or /etc/example.conf.d

Parameters:

usr_conf_dir – absolute path of the first directory to be searched
etc_conf_dir – absolute path of the second directory to be searched
project_name – basename of the configuration file
config_suffix – suffix of the configuration file
delim – delimiter of a key/value e.g. ‘=’
comment – string that defines the start of a comment e.g. ‘#’
callback – User defined function which will be called for each file and returns a boolean
callback_data – argument to be give to the callback function

Returns:

merged EconfFile object

Read configuration from the first found config file and snippets from conf.d/ directory

e.g. searches /usr/etc/ and /etc/ for an example.conf file and the snippets in either /usr/etc/example.conf.d/ or /etc/example.conf.d

Parameters:

usr_conf_dir – absolute path of the first directory to be searched
etc_conf_dir – absolute path of the second directory to be searched
project_name – basename of the configuration file
config_suffix – suffix of the configuration file
delim – delimiter of a key/value e.g. ‘=’
comment – string that defines the start of a comment e.g. ‘#’

Returns:

list of EconfFile objects

Read configuration from the first found config file and snippets from conf.d/ directory

For every file a user defined function will be called in order e.g. to check the correct file permissions. If the function returns False the parsing will be aborted and an Exception will be raised

e.g. searches /usr/etc/ and /etc/ for an example.conf file and the snippets in either /usr/etc/example.conf.d/ or /etc/example.conf.d

Parameters:

usr_conf_dir – absolute path of the first directory to be searched
etc_conf_dir – absolute path of the second directory to be searched
project_name – basename of the configuration file
config_suffix – suffix of the configuration file
delim – delimiter of a key/value e.g. ‘=’
comment – string that defines the start of a comment e.g. ‘#’
callback – User defined function which will be called for each file and returns a boolean
callback_data – argument to be give to the callback function

Returns:

list of EconfFile objects

econf.comment_tag(ef: EconfFile) → str

Get the comment tag of the specified EconfFile

Parameters:: ef – Key-Value storage object
Returns:: The comment tag of the EconfFile

econf.set_comment_tag(ef: EconfFile, comment: str | bytes) → None

Set the comment tag of the specified EconfFile

Parameters:

ef – Key-Value storage object
comment – The desired comment tag character

Returns:

Nothing

econf.delimiter_tag(ef: EconfFile) → str

Get the delimiter tag of the specified EconfFile

Parameters:: ef – Key-Value storage object
Returns:: the delimiter tag of the EconfFile

econf.set_delimiter_tag(ef: EconfFile, delimiter: str | bytes) → None

Set the delimiter tag of the specified EconfFile

Parameters:

ef – Key-Value storage object
delimiter – The desired delimiter character

Returns:

Nothing

econf.write_file(ef: EconfFile, save_to_dir: str, file_name: str) → None

Write content of a keyfile to specified location

Parameters:

ef – Key-Value storage object
save_to_dir – directory into which the file has to be written
file_name – filename with suffix of the to be written file

Returns:

Nothing

econf.get_path(ef: EconfFile) → str

Get the path of the source of the given key file

Parameters:: ef – Key-Value storage object
Returns:: path of the config file as string

Functions for getting values

econf.get_groups(ef: EconfFile) → list[str]

List all the groups of given keyfile

Parameters:: ef – Key-Value storage object
Returns:: list of groups in the keyfile

econf.get_keys(ef: EconfFile, group: str) → list[str]

List all the keys of a given group or all keys in a keyfile

Parameters:

ef – Key-Value storage object
group – group of the keys to be returned or None for keys without a group

Returns:

list of keys in the given group

econf.get_int_value(ef: EconfFile, group: str, key: str) → int

Return an integer value for given group/key

Parameters:

ef – Key-Value storage object
group – desired group
key – key of the value that is requested

Returns:

value of the key

econf.get_uint_value(ef: EconfFile, group: str, key: str) → int

Return an unsigned integer value for given group/key

Parameters:

ef – Key-Value storage object
group – desired group
key – key of the value that is requested

Returns:

value of the key

econf.get_float_value(ef: EconfFile, group: str, key: str) → float

Return a float value for given group/key

Parameters:

ef – Key-Value storage object
group – desired group
key – key of the value that is requested

Returns:

value of the key

econf.get_string_value(ef: EconfFile, group: str, key: str) → str

Return a string value for given group/key

Parameters:

ef – Key-Value storage object
group – desired group
key – key of the value that is requested

Returns:

value of the key

econf.get_bool_value(ef: EconfFile, group: str, key: str) → bool

Return a boolean value for given group/key

Parameters:

ef – Key-Value storage object
group – desired group
key – key of the value that is requested

Returns:

value of the key

Functions for getting values with defaults

econf.get_int_value_def(ef: EconfFile, group: str, key: str, default: int) → int

Return an integer value for given group/key or return a default value if key is not found

Parameters:

ef – Key-Value storage object
group – desired group
key – key of the value that is requested
default – value to be returned if no key is found

Returns:

value of the key

econf.get_uint_value_def(ef: EconfFile, group: str, key: str, default: int) → int

Return an unsigned integer value for given group/key or return a default value if key is not found

Parameters:

ef – Key-Value storage object
group – desired group
key – key of the value that is requested
default – value to be returned if no key is found

Returns:

value of the key

econf.get_float_value_def(ef: EconfFile, group: str, key: str, default: float) → float

Return a float value for given group/key or return a default value if key is not found

Parameters:

ef – Key-Value storage object
group – desired group
key – key of the value that is requested
default – value to be returned if no key is found

Returns:

value of the key

econf.get_string_value_def(ef: EconfFile, group: str, key: str, default: str) → str

Return a string value for given group/key or return a default value if key is not found

Parameters:

ef – Key-Value storage object
group – desired group
key – key of the value that is requested
default – value to be returned if no key is found

Returns:

value of the key

econf.get_bool_value_def(ef: EconfFile, group: str, key: str, default: bool) → bool

Return a boolean value for given group/key or return a default value if key is not found

Parameters:

ef – Key-Value storage object
group – desired group
key – key of the value that is requested
default – value to be returned if no key is found

Returns:

value of the key

Functions for setting values

Dynamically set a value in a keyfile and returns a status code

Parameters:

ef – EconfFile object to set value in
group – group of the key to be changed
key – key to be changed
value – desired value

Returns:

Nothing

econf.set_int_value(ef: EconfFile, group: str, key: str, value: int) → None

Setting an integer value for given group/key

Parameters:

ef – Key-Value storage object
group – desired group
key – key of the value that is requested
value – value to be set for given key

Returns:

Nothing

econf.set_uint_value(ef: EconfFile, group: str, key: str, value: int) → None

Setting an unsigned integer value for given group/key

Parameters:

ef – Key-Value storage object
group – desired group
key – key of the value that is requested
value – value to be set for given key

Returns:

Nothing

econf.set_float_value(ef: EconfFile, group: str, key: str, value: float) → None

Setting a float value for given group/key

Parameters:

ef – Key-Value storage object
group – desired group
key – key of the value that is requested
value – value to be set for given key

Returns:

Nothing

econf.set_string_value(ef: EconfFile, group: str, key: str, value: str | bytes) → None

Setting a string value for given group/key

Parameters:

ef – Key-Value storage object
group – desired group
key – key of the value that is requested
value – value to be set for given key

Returns:

Nothing

econf.set_bool_value(ef: EconfFile, group: str, key: str, value: bool) → None

Setting a boolean value for given group/key

Parameters:

ef – Key-Value storage object
group – desired group
key – key of the value that is requested
value – value to be set for given key

Returns:

Nothing

Functions for memory management

econf.free_file(ef: EconfFile)

Free the memory of a given keyfile

This function is called automatically at the end of every objects lifetime and should not be used otherwise

Parameters:: ef – EconfFile to be freed
Returns:: None

Functions for handling error codes

econf.err_string(error: int) → str

Convert an error code into error message

Parameters:: error – error code as integer
Returns:: error string

econf.err_location() → Tuple[str, int]

Info about the line where an error happened

Returns:: path to the last handled file and number of last handled line