ConfigParserEnhanced

DEPRECATION NOTICE

This package was forked by the original author and subdivided into separate packages:

• ConfigParserEnhanced ⟶ ActiveConfigParser (GitLab, PyPI, Docs)

• Debuggable ⟶ LightweightDebugMessages (GitLab, PyPI, Docs)

• ExceptionControl ⟶ ExceptionControl (GitLab, PyPI, Docs)

• TypedProperty ⟶ StronglyTypedProperty (GitLab, PyPI, Docs)

Users of ConfigParserEnhanced should switch to the new packages.

Table of Contents:

• ConfigParserEnhanced Class Reference
• Debuggable Class Reference
• ExceptionControl Class Reference
• HandlerParameters Class Reference
• TypedProperty Reference
• License

Indices and Tables

• Index

• Module Index

Overview

The ConfigParserEnhanced (CPE) package provides extended handling of .ini files beyond what ConfigParser provides by adding an active syntax to embed operations with options.

For example, a standard .ini file is generally formatted like this:

[Section 1]
Foo: Bar
Baz: Bif

[Section 2]
Foo: Bar2
Bif: Baz

These files are used to organize sets of key - value pairs called “options” within groups called “sections”. In the example above there are two sections, “Section 1” and “Section 2”. Each of them contains two options where Section 1 has the keys ‘Foo’ and ‘Baz’ which are assigned the values ‘Bar’ and ‘Bif’, respectively. For more details on .ini files please see the documentation for ConfigParser.

ConfigParserEnhanced extends the processing capabilities for .ini files by adding an active component of handling of each option. This allows us to merge the processing with the reading of each option. In this model, we treat individual options according to the following syntax:

operation param1 param2 ... 'param with spaces' ... paramN : value

The entries on an option in the key portion are space-separated generally and the first entry can be considered the operation. CPE will attempt to map the detected operation to a handler method and if a matching one is found then it will send the option to that handler for processing. Options that do not map to a handler will be treated as a standard “key:value” pair.

Internally, these handlers methods defined according to a naming convention like handler_<operation>().

CPE only provides one pre-defined operation: use which is formatted as use TARGET: where param1 is the TARGET (there is no value field for this one). The TARGET paramter takes the name of a target section that will be loaded in at this point. This works in the same way a #include would work in C++ and serves to insert the contents or processing of the target section into this location.

The use operation is useful for .ini files for complex systems by allowing developers to create a common section and then have specializations where they can customize options for a given project. For example:

[COMMON]
Key C1: Value C1
Key C2: Value C2
Key C3: Value C3

[Data 1]
Key D1: Value D1
use COMMON
Key D2: Value D2

In this example, processing section Data 1 via CPE will result in the following options: Key D1: Value D1, Key C1: Value C1, Key C2: Value C2, Key C2: Value C2, Key D2: Value D2.

An alternative way of looking at this is it’s like having a .ini file that is effectively the following where the use operations are replaced with the results of a Depth-First expansion of the linked sections:

[COMMON]
Key C1: Value C1
Key C2: Value C2
Key C3: Value C3

[Data 1]
Key D1: Value D1
Key C1: Value C1
Key C2: Value C2
Key C3: Value C3
Key D2: Value D2

Examples

Here we show example usages of ConfigParserEnhanced. These examples can be found in the examples/ directory of the repository.

Example 1

example-01.ini

[SECTION-A]
key A1 : value A1
key A2 : value A2
key A3 : value A3

[SECTION-B]
use SECTION-A:
key B1 : value B1

ConfigParserEnhanced-example-01.py

#!/usr/bin/env python3
# -*- mode: python; py-indent-offset: 4; py-continuation-offset: 4 -*-
"""
Example application that uses ConfigParserEnhanced
"""
from __future__ import print_function # python 2 -> 3 compatiblity

from configparserenhanced import ConfigParserEnhanced



def test_configparserEnhanced(filename="config.ini"):
    print(f"Using filename: `{filename}`\n")

    parser = ConfigParserEnhanced(filename=filename)

    # Additional ConfigParserEnhanced flags:
    #parser.debug_level = 5
    #parser.exception_control_level = 4
    #parser.exception_control_compact_warnings = True
    #parser.exception_control_silent_warnings  = False

    section_name = "SECTION-B"

    parser.parse_section(section_name)

    print(f"Section data for `{section_name}`:")
    section = parser.configparserenhanceddata[section_name]
    print(f"{section}")

    print("")
    print("Section List:")
    for section_name in parser.configparserenhanceddata.sections():
        print(f"- {section_name}")

    print("")
    print("Section Details:")
    for section_name, options in parser.configparserenhanceddata.items():
        print(f"[{section_name}]")
        for key, value in options.items():
            print(f"{key} : {value}")
        print("")

    # Write out a 'collapsed' version of the .ini file
    with open("_example-01-parsed.ini", "w") as ofp:
        parser.write(ofp)
    return 0



if __name__ == "__main__":
    test_configparserEnhanced(filename="example-01.ini")
    print("Done.")

Console Output

Using filename: `example-01.ini`

Section data for `SECTION-B`:
{'key A1': 'value A1', 'key A2': 'value A2', 'key A3': 'value A3', 'key B1': 'value B1'}

Section List:
- SECTION-A
- SECTION-B

Section Details:
[SECTION-B]
key A1 : value A1
key A2 : value A2
key A3 : value A3
key B1 : value B1

[SECTION-A]
key A1 : value A1
key A2 : value A2
key A3 : value A3

Done.