libconf

Warnings

• breaking Starting with version 2.0.0, `libconf` introduced output validation for `dump()` and `dumps()`. These functions will now raise exceptions if attempting to dump data that cannot be correctly read by a standard C libconfig implementation.
  Fix: Review data structures being dumped for compatibility with the libconfig specification. Ensure that values and structures adhere to libconfig's rules to avoid `libconf.ConfigError` or similar exceptions.
• gotcha Python integer values are dumped without an 'L' suffix if they fit within a C/C++ 32-bit integer range. For larger Python integers, an 'L' suffix is automatically appended. If you need to force an 'L' suffix for a number within the 32-bit range (e.g., for explicit 64-bit representation in libconfig), wrap the integer with `libconf.LibconfInt64`.
  Fix: To explicitly dump an integer as a 64-bit value with an 'L' suffix, use `config_data['key'] = LibconfInt64(your_int_value)` before dumping.
• gotcha libconfig distinguishes between 'lists' (enclosed by parentheses `()`, arbitrary values) and 'arrays' (enclosed by brackets `[]`, scalar values of the same type). `libconf` maps libconfig `()`-lists to Python `tuples` and libconfig `[]`-arrays to Python `lists`. This distinction is important when round-tripping data or ensuring compatibility with C libconfig.
  Fix: When reading, be aware that libconfig lists will become Python tuples. When writing, use Python tuples for libconfig lists and Python lists for libconfig arrays, keeping in mind the type homogeneity requirement for arrays.
• gotcha It is strongly recommended to use Unicode objects (Python 3 `str`) for all input strings or streams passed to `load()` and `loads()`, and for any strings within data structures passed to `dump()` and `dumps()`. `libconf` handles standard escape sequences (`\n`, `\r`, `\t`, `\xNN`).
  Fix: Always ensure strings are Unicode/`str` type in Python 3. If dealing with byte strings or specific encodings, decode them to Unicode before passing to `libconf` functions.

Install

• pip install libconf Install libconf

Imports

• libconf

  import libconf

• LibconfInt64

  from libconf import LibconfInt64

  Used for fine-grained control over integer output formatting.
• LibconfList

  from libconf import LibconfList

  Used for fine-grained control over list output formatting.
• LibconfArray

  from libconf import LibconfArray

  Used for fine-grained control over array output formatting.

Quickstart

This quickstart demonstrates how to load a libconfig string into a Python object, access its elements using attribute or dictionary-style access, modify values, and then dump the modified configuration back into a libconfig formatted string. It also shows the use of `LibconfInt64` for explicit control over integer suffixes. For file operations, `libconf.load()` and `libconf.dump()` are available, similar to the `json` module.

import libconf
import io

# Example libconfig string
config_string = """
version = 2;
window : {
  title = "My Application";
  position = { x = 10; y = 20; w = 800; h = 600; };
};
capabilities = (
  true,
  1234567890123456789L,
  [1, 2, 3]
);
"""

# Load configuration from a string
config = libconf.loads(config_string)
print("Loaded Config:", config)
print("Window Title:", config.window.title)

# Modify and dump configuration back to a string
config.window.title = "Updated App Title"
config.capabilities = ('new_list_item', 42)

# Demonstrate LibconfInt64 for explicit long suffix
from libconf import LibconfInt64
config['large_number_forced_L'] = LibconfInt64(123)

dumped_string = libconf.dumps(config, indent=2)
print("\nDumped Config:\n", dumped_string)