PYTHON-LIBECONF(3)

python-libeconf is a Python Library which offers Python bindings for libeconf.

libeconf is a highly flexible and configurable library to parse and manage key=value configuration files. It reads configuration file snippets from different directories and builds the final configuration file for the application from it.

CONTENTS

  Usage

  install

WARNING: The recommended way to install this project is to get it via your distro package manager. If you install this project from pypi libeconf will not be automatically installed. To use this project please make sure you have libeconf installed on your system!

You can install this project from pypi with

pip install python-libeconf

and then import it into your python project with

import econf

For information about the functions provided by this library, have a look at the API section

  usage example

>>> import econf
>>> file = econf.read_file("examples/etc/example/example.conf", "=", "#")
>>> econf.get_groups(file)
['Another Group', 'First Group', 'Group']
>>> econf.get_keys(file, "Group")
['Bla', 'Welcome[la]', 'Welcome']
>>> econf.get_int_value(file, "Group", "Bla")
12311
>>> econf.set_int_value(file, "Group", "Bla", 5)
>>> econf.get_int_value(file, "Group", "Bla")
5
>>> econf.write_file(file, "examples/etc/example", "example_new.conf")
>>>

  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

econf.read_config(project: str |bytes, usr_conf_dir: str | bytes, config_name: str | bytes, config_suffix: str | bytes, delim: str | bytes, comment: str | bytes) -> EconfFile
    Evaluating key/values of a given configuration by reading and merging all needed/available files from different directories.

    This call fulfills all requirements, defined by the Linux Userspace API (UAPI) Group chapter "Configuration Files Specification".

Parameters

•   project – name of the project used as subdirectory

•   usr_conf_dir – absolute path of the first directory to be searched

•   config_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

econf.read_config_with_callback(project: str | bytes, usr_conf_dir: str | bytes, config_name: str | bytes, config_suffix: str | bytes, delim: str | bytes, comment: str | bytes, callback: Callable[[any], bool], callback_data: any) -> EconfFile
    Evaluating key/values of a given configuration by reading and merging all needed/available files from different directories.

    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

    This call fulfills all requirements, defined by the Linux Userspace API (UAPI) Group chapter "Configuration Files Specification".

Parameters

•   project – name of the project used as subdirectory

•   usr_conf_dir – absolute path of the first directory to be searched

•   config_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

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

econf.set_value(ef: EconfFile, group: str | bytes, key: str | bytes, value: int | float | str | bool) -> None
    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

AUTHOR
Nico Krapp

COPYRIGHT
2023, Nico Krapp