| PYTHON-LIBECONF(3) | python-libeconf | 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
- 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
- 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
- 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
- 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".
- 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".
- 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
- 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
- econf.write_file(ef: EconfFile, save_to_dir: str, file_name: str) -> None
- Write content of a keyfile to specified location
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
| November 13, 2023 |