Examples

This page contains the raw code + output of our examples. For detailed explanations of what is going on please see the Quick Start guide.

Example 1 - Basic Example

See Example: Basic Usage in the QuickStart guide for a detailed explanation of this example.

Input File Listing: Example 1

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

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

Code Listing: Example 1#!/usr/bin/env python3
# -*- mode: python; py-indent-offset: 4; py-continuation-offset: 4 -*-
"""
ActiveConfigParser example showing the basics.
"""
from activeconfigparser import ActiveConfigParser


filename = "ActiveConfigParser-example-01.ini"
print(f"Using filename: `{filename}`\n")

# Create the parser
parser = ActiveConfigParser(filename=filename)

# Additional ActiveConfigParser flags (optional)
#parser.debug_level = 5
#parser.exception_control_level = 4
#parser.exception_control_compact_warnings = True
#parser.exception_control_silent_warnings  = False

# Parse SECTION-B
section_name = "SECTION-B"
parser.parse_section(section_name)

# Extract the properties of the section as a dictionary
print(f"Section data for `{section_name}`:")
section = parser.activeconfigparserdata[section_name]
print(f"{section}")
print("")

# List the section names
print("Section List:")
for section_name in parser.activeconfigparserdata.sections():
    print(f"- {section_name}")
print("")

# Walk through the details of all sections in the file:
print("Section Details:")
for section_name, options in parser.activeconfigparserdata.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("_ActiveConfigParser-example-01-parsed.ini", "w") as ofp:
    parser.write(ofp)

Output: Example 1

Program execution output:

Using filename: `ActiveConfigParser-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

Parsed output file:

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

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

Example 2 - Cyclic Dependency

In this example we add a cyclic dependency into the .ini file. Generally this is a bad idea because a dependency graph of the sections should createa DAG but we try and handle it.

The default behaviour is to treat this as an accident that should be noted so we generate a warning and we don’t follow the back-edge in our DFS traversal. This warning can be changed to an exception by changing the exception_control_level parameter to 5.

Input File Listing: Example 2

We add the use SECCTION-B operation into SECTION-A on line 4.

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

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

Code Listing: Example 2#!/usr/bin/env python3
# -*- mode: python; py-indent-offset: 4; py-continuation-offset: 4 -*-
"""
ActiveConfigParser example demonstrating handling .ini files
with cyclic dependencies across ``use`` operations.
"""
from __future__ import print_function # python 2 -> 3 compatiblity
from activeconfigparser import ActiveConfigParser


filename = "ActiveConfigParser-example-02.ini"
print(f"Using filename: `{filename}`\n")

# Create the parser
parser = ActiveConfigParser(filename=filename)

# Additional ActiveConfigParser flags (optional)
#parser.debug_level = 5
#parser.exception_control_level = 4
#parser.exception_control_compact_warnings = True
#parser.exception_control_silent_warnings  = False

# Parse SECTION-B
section_name = "SECTION-B"
parser.parse_section(section_name)

# Extract the properties of the section as a dictionary
print(f"Section data for `{section_name}`:")
section = parser.activeconfigparserdata[section_name]
print(f"{section}")
print("")

## Write out a 'collapsed' version of the .ini file
with open("_ActiveConfigParser-example-02-parsed.ini", "w") as ofp:
    parser.write(ofp)

Output: Example 2

Here we see the output with the warning generated. The general format of the warnings is controled by ExceptionControl but the general format is to prefix the warning message lines with a !! to allow easy searching in large log files.

Using filename: `ActiveConfigParser-example-02.ini`

!! ================================================================================
!! EXCEPTION SKIPPED
!! Event Type : WARNING
!! Exception  : ValueError
!! Message    : Detected a cycle in `use` dependencies in .ini file [PosixPath('ActiveConfigParser-example-02.ini')].
!!            : - cannot load [SECTION-B] from [SECTION-A].
!!
!! Call Stack:
!! File "/builds/semantik-software/code/python/ActiveConfigParser/examples/ActiveConfigParser-example-02.py", line 25, in <module>
!!     parser.parse_section(section_name)
!! File "/builds/semantik-software/code/python/ActiveConfigParser/venv-examples/lib/python3.14/site-packages/activeconfigparser/ActiveConfigParser.py", line 685, in parse_section
!!     result = self._parse_section_r(section, initialize=initialize, finalize=finalize)
!! File "/builds/semantik-software/code/python/ActiveConfigParser/venv-examples/lib/python3.14/site-packages/activeconfigparser/ActiveConfigParser.py", line 1008, in _parse_section_r
!!     ophandler_f(section_name, handler_parameters)
!! File "/builds/semantik-software/code/python/ActiveConfigParser/venv-examples/lib/python3.14/site-packages/activeconfigparser/ActiveConfigParser.py", line 722, in wrapper
!!     output = func_handler(self, section_name, handler_parameters)
!! File "/builds/semantik-software/code/python/ActiveConfigParser/venv-examples/lib/python3.14/site-packages/activeconfigparser/ActiveConfigParser.py", line 1339, in _handler_use
!!     self._parse_section_r(op2, handler_parameters, finalize=False)
!! File "/builds/semantik-software/code/python/ActiveConfigParser/venv-examples/lib/python3.14/site-packages/activeconfigparser/ActiveConfigParser.py", line 1008, in _parse_section_r
!!     ophandler_f(section_name, handler_parameters)
!! File "/builds/semantik-software/code/python/ActiveConfigParser/venv-examples/lib/python3.14/site-packages/activeconfigparser/ActiveConfigParser.py", line 722, in wrapper
!!     output = func_handler(self, section_name, handler_parameters)
!! File "/builds/semantik-software/code/python/ActiveConfigParser/venv-examples/lib/python3.14/site-packages/activeconfigparser/ActiveConfigParser.py", line 1346, in _handler_use
!!     self.exception_control_event("WARNING", ValueError, message)
!!
!! Increase `exception_control_level` to 5 to raise this exception.
!! ================================================================================
Section data for `SECTION-B`:
{'key A1': 'value A1', 'key A2': 'value A2', 'key A3': 'value A3', 'key B1': 'value B1'}

The same as in Example 01, we also save out the unrolled version of the parsed file. This differs from Example 01 in that we have key B1 inserted into SECTION-A on line 4.

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

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

Example 3 - Add Custom Operations

See Example: Add Custom Operations in the QuickStart guide for a detailed explanation of this example.

Input File Listing: Example 3

This .ini files includes the custom operation hello that we will create in a custom class that extends ActiveConfigParser.

[SECTION-A]
hello:
hello world:
hello world earth: moon

Code Listing: Example 3

The source code:

#!/usr/bin/env python3
# -*- mode: python; py-indent-offset: 4; py-continuation-offset: 4 -*-
"""
This example demonstrates how one can extend ActiveConfigParser to
create new configuration file parser that has new operations.
"""
from __future__ import print_function # python 2 -> 3 compatiblity
from activeconfigparser import ActiveConfigParser



class MyActiveConfigParser(ActiveConfigParser):

    def __init__(self, filename=None):
        if filename is not None:
            # self.inifilepath is an ActiveConfigParser property
            self.inifilepath = filename
        return

    @ActiveConfigParser.operation_handler
    def _handler_hello(self, section_name, handler_parameters) -> int:
        op = handler_parameters.op
        param = handler_parameters.params
        value = handler_parameters.value
        print(f"HELLO!")
        print(f"- op   : {op}")
        print(f"- param: {param}")
        print(f"- value: {value}")
        return 0



filename = "ActiveConfigParser-example-03.ini"
print(f"Using filename: `{filename}`\n")

# Create the parser
parser = MyActiveConfigParser(filename=filename)

# Additional ActiveConfigParser flags (optional)
#parser.debug_level = 5
#parser.exception_control_level = 4
#parser.exception_control_compact_warnings = True
#parser.exception_control_silent_warnings  = False

# Parse SECTION-A
section_name = "SECTION-A"
parser.parse_section(section_name)

The custom class MyActiveConfigParser is created to extend ActiveConfigParser and we add our custom handler for the hello operation in the _handler_hello method.

Output: Example 3

Using filename: `ActiveConfigParser-example-03.ini`

HELLO!
- op   : hello
- param: []
- value: 
HELLO!
- op   : hello
- param: ['world']
- value: 
HELLO!
- op   : hello
- param: ['world', 'earth']
- value: moon