ERBSLAND CONFIG FOR PYTHON

Installation and Quick Example

pip install erbsland-conf

Here’s a minimal Python example showing how to load a configuration file, access values with type checks, and handle errors gracefully:

import erbsland.conf as elcl

def parse_configuration(file_name: str):
    doc = elcl.load(file_name)
    # Access required values and check the type.
    server_name = doc.get_text("main.server.name")
    # Provide a default if the value is optional.
    port = doc.get_int("main.server.port", default=8080)
    # Iterating over section lists naturally.
    for client_value in doc["client"]:
        name = client_value.get_text("name")
        ip = client_value.get_text("ip")
        port = client_value.get_int("port", default=9000)

        # Reading values from optional sections.
        if filter_value := client_value.get("filter", default=None):
            # Requiring lists of specific types.
            keywords = filter_value.get_list("keywords", str)
            # ...
        # ...
    # ...

def main():
    try:
        parse_configuration("quick-intro.elcl")
        # ... running the application ...
        exit(0)
    except elcl.Error as e:
        print("Error reading the configuration.")
        print(e.to_text(elcl.ErrorOutput.FILENAME_ONLY | elcl.ErrorOutput.USE_LINES))
        exit(1)

if __name__ == "__main__":
    main()

Why Use this Erbsland Configuration Parser?

This Python implementation was designed to be practical, reliable, and easy to use. It is one of the official implementations of the Erbsland Configuration Language (ELCL), with clear goals in mind:

• No dependencies – Requires only Python 3.12 or newer.
• Expressive interface – Reduces boilerplate, keeping integration clean and concise.
• Security & robustness – Production-ready, with safe error handling and predictable behavior.
• Full feature coverage – Implements the complete ELCL specification, including:
  • Core features: names, values, sections
  • Standard features: multiline values, byte counts, lists
  • Advanced features: regular expressions, code blocks, time deltas
• Reference design – Not only a library you can rely on, but also a guide for developers who want to implement their own ELCL parsers.

In short: if you want a configuration system that is modern, complete, and Pythonic, this parser has you covered.

Catch-all Error Handling

Working with configuration files often means dealing with a variety of potential issues—from syntax errors to unexpected value types. This parser takes the pain out of that process by using a unified error system that covers:

• Problems while reading or parsing a file
• IO errors such as missing or unreadable files
• Type mismatches and other issues when accessing values

Instead of juggling multiple exception types, you can wrap your parsing logic in a single try...except block and handle all errors consistently.

import erbsland.conf as elcl

def parse_configuration(file_name: str):
    doc = elcl.load(file_name)
    server_name = doc.get_text("main.server.name")
    port = doc.get_int("main.server.port", default=8080)
    # ...

def main():
    try:
        parse_configuration("error_handling_4.elcl")
        print("Success!")
        exit(0)
    except elcl.Error as e:
        print("Error reading the configuration.")
        print(e.to_text(elcl.ErrorOutput.FILENAME_ONLY | elcl.ErrorOutput.USE_LINES))
        exit(1)

If something goes wrong—like a missing section or a wrong type—you’ll see a clear and user-friendly error message:

Error reading the configuration.
Expected value of type Text, got Integer
    source: file:error_handling_4.elcl:[7:22]
    name-path: main.server.name

These messages give you both practical context and technical precision:

• The name path explains which key caused the problem.
• The file path, line, and column point you directly to the spot in the source.

This way, errors are straightforward to track down and fix, even in larger or more complex configurations.

Requirements

This library was designed to run on modern Python with no extra baggage.

Runtime Requirements

• Python 3.12 or newer
• No external dependencies—just the standard library

Optional (for contributors and testing)

• Python 3.12+ (for running the test suite)

That’s it. Install the package, import it, and you’re ready to go—no compiling, no C extensions, no hidden extras.

Design Goals

The Python implementation of the Erbsland Configuration Language was created with a clear set of goals in mind:

• No Dependencies Runs on Python 3.12+ with nothing but the standard library.

• Expressive API Keeps code clean and concise, reducing boilerplate when working with configurations.

• Security & Robustness Provides safe error handling and predictable behavior across all supported features.

• Full Feature Coverage Supports the entire ELCL specification, including core elements (names, values, sections), standard features (multiline values, byte counts, lists), and advanced types (regex, code blocks, time deltas).

• Practical & Educational A production-ready parser that also serves as a guide for developers interested in implementing their own ELCL parsers.

These goals ensure the library is not only easy to use in Python projects, but also a solid reference for the ELCL ecosystem.

Sources and License

The complete source code of Erbsland Configuration Parser for Python is available on GitHub. The project is licensed under the Apache License 2.0.

This permissive license allows you to use the library in both open-source and proprietary projects, giving you maximum flexibility in how you integrate it into your software.