PYTHON-LIBECONF(3)

📦 version 0.7.9, in opensuse-leap 16.0

💖 python-libeconf 💖

okay so bestie, welcome to python-libeconf(3) — that's the python-libeconf manual, section 3, if you're keeping track 👑

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

And libeconf? She's a highly flexible and configurable library to parse and manage key=value configuration files. The whole serve is that she reads configuration file snippets from different directories and builds the final configuration file for the application from it. It's giving assembly line, but make it config 🎀

📚 CONTENTS

  • Usage
    • install
    • usage example
    • API

🚀 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! No cap, check first 😭

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

like, literally just vibe with it:

>>> 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")
>>>

ate, honestly 💅

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". Like, certified iconic 👑

  • 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 🎀
    • 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 ✏️
    • 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 🍓
    • 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 ✏️
    • 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 💾
    • 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 🗺️
    • 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 🌸
    • 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

Okay so this little family of five is literally my favorite thing ever — every single one of them does the exact same bit: try to get a value from a group/key, and if that key is not there, hand you back a default instead of crying. No exceptions, no drama, we love a safety net 🫶

✨ econf.get_int_value_def

econf.get_int_value_def(ef: EconfFile, group: str, key: str, default: int) -> int

Returns an integer value for the given group/key, or the default value if the key is not found.

Parameters

  • ef — the Key-Value storage object
  • group — the group you want
  • key — the key of the value you're requesting
  • default — the value that comes back if no key is found

Returns — the value of the key 💅

✨ econf.get_uint_value_def

econf.get_uint_value_def(ef: EconfFile, group: str, key: str, default: int) -> int

Returns an unsigned integer value for the given group/key, or the default value if the key is not found. Same energy, no negatives allowed bestie 🚫

Parameters

  • ef — the Key-Value storage object
  • group — the group you want
  • key — the key of the value you're requesting
  • default — the value that comes back if no key is found

Returns — the value of the key 🌸

✨ econf.get_float_value_def

econf.get_float_value_def(ef: EconfFile, group: str, key: str, default: float) -> float

Returns a float value for the given group/key, or the default value if the key is not found. Decimals girlies rise ✨

Parameters

  • ef — the Key-Value storage object
  • group — the group you want
  • key — the key of the value you're requesting
  • default — the value that comes back if no key is found

Returns — the value of the key 🦋

✨ econf.get_string_value_def

econf.get_string_value_def(ef: EconfFile, group: str, key: str, default: str) -> str

Returns a string value for the given group/key, or the default value if the key is not found. Text? iconic, obsessed 💜

Parameters

  • ef — the Key-Value storage object
  • group — the group you want
  • key — the key of the value you're requesting
  • default — the value that comes back if no key is found

Returns — the value of the key 🎀

✨ econf.get_bool_value_def

econf.get_bool_value_def(ef: EconfFile, group: str, key: str, default: bool) -> bool

Returns a boolean value for the given group/key, or the default value if the key is not found. Yes/no, true/false, slay/not slay 💀

Parameters

  • ef — the Key-Value storage object
  • group — the group you want
  • key — the key of the value you're requesting
  • default — the value that comes back if no key is found

Returns — the value of the key ⭐

🎀 Functions for setting values

Now we flip it — instead of reading, we're writing into the keyfile. Main character energy fr fr 👑

💅 econf.set_value

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

Dynamically sets a value in a keyfile and returns a status code.

Parameters

  • ef — the EconfFile object to set the value in
  • group — the group of the key to be changed
  • key — the key to be changed
  • value — the value you want

Returns — nothing

ngl the description says it returns a status code but the Returns line says Nothing — that's just how the page is written, so I'm passing it to you exactly as-is 🙈

💅 econf.set_int_value

econf.set_int_value(ef: EconfFile, group: str, key: str, value: int) -> None

Sets an integer value for the given group/key.

Parameters

  • ef — the Key-Value storage object
  • group — the group you want
  • key — the key of the value you're requesting
  • value — the value to be set for the given key

Returns — nothing 🌈

💅 econf.set_uint_value

econf.set_uint_value(ef: EconfFile, group: str, key: str, value: int) -> None

Sets an unsigned integer value for the given group/key.

Parameters

  • ef — the Key-Value storage object
  • group — the group you want
  • key — the key of the value you're requesting
  • value — the value to be set for the given key

Returns — nothing 🧚

💅 econf.set_float_value

econf.set_float_value(ef: EconfFile, group: str, key: str, value: float) -> None

Sets a float value for the given group/key.

Parameters

  • ef — the Key-Value storage object
  • group — the group you want
  • key — the key of the value you're requesting
  • value — the value to be set for the given key

Returns — nothing 🍓

💅 econf.set_string_value

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

Sets a string value for the given group/key. Note the str | bytes on value — both are welcome here 💖

Parameters

  • ef — the Key-Value storage object
  • group — the group you want
  • key — the key of the value you're requesting
  • value — the value to be set for the given key

Returns — nothing 🦋

💅 econf.set_bool_value

econf.set_bool_value(ef: EconfFile, group: str, key: str, value: bool) -> None

Sets a boolean value for the given group/key.

Parameters

  • ef — the Key-Value storage object
  • group — the group you want
  • key — the key of the value you're requesting
  • value — the value to be set for the given key

Returns — nothing ✨

🧚 Functions for memory management

Short section, but honestly the most important warning on this whole page. Pay attention bestie 👀

econf.free_file

econf.free_file(ef: EconfFile)

Frees the memory of a given keyfile.

⚠️ This function is called automatically at the end of every object's lifetime and should not be used otherwise. Like, don't touch it. It's already handling itself. Using it manually is giving "double free" and we do not want that 😭

Parameters

  • ef — the EconfFile to be freed

Returns — None

🔥 Functions for handling error codes

When things go sideways (they won't, but like, if), these two are your group chat when something breaks 💀

econf.err_string

econf.err_string(error: int) -> str

Converts an error code into an error message.

Parameters

  • error — the error code, as an integer

Returns — the error string 🌸

econf.err_location

econf.err_location() -> Tuple[str, int]

Info about the line where an error happened.

Returns — the path to the last handled file and the number of the last handled line 🫶

👑 AUTHOR

Nico Krapp

2023, Nico Krapp

okay that's the whole page, you're officially a libeconf girlie now 💅✨ mwah, go parse something pretty — this page was from Nov 13, 2023 and it's the PYTHON-LIBECONF(3) manual, so go forth and set some values 🎀🦋

📦 where this page comes from