Configuration

Module Configuration provides an abstract configuration reader.

It supports any configuration file syntax, which provides:

• scalar elements (integer, string, …),

• sequences (ordered lists), and

• dictionaries (key-value-pairs).

The abstracted data model is based on a common Node class, which is derived to a Sequence, Dictionary and Configuration class.

Inheritance diagram:

Dictionary

A Dictionary represents key-value-pairs of information.

JSON

// one-liner style
{"key1": "item1", "key2": "item2", "key3": "item3"}

// multi-line style
{
  "key1": "item1",
  "key2": "item2",
  "key3": "item3"
}

TOML

# one-liner style
section_1 = {key1 = "item1", key2 = "item2", key3 = "item3"}

# section style
[section_2]
key1 = "item1"
key2 = "item2"
key3 = "item3"

YAML

# one-liner style
{key1: item1, key2: item2, key3: item3}

# multi-line style
key1: item1
key2: item2
key3: item3

XML

<items>
  <item key="key1">item1</item>
  <item key="key2">item2</item>
  <item key="key3">item3</item>
</items>

Todo

CONFIG:: Needs documentation for Dictionary

Sequences

A Sequence represents ordered information items.

JSON

// one-liner style
["item1", "item2", "item3"]

// multi-line style
[
  "item1",
  "item2",
  "item3"
]

TOML

# one-liner style
section_1 = ["item1", "item2", "item3"]

# multi-line style
section_2 = [
  "item1",
  "item2",
  "item3"
]

YAML

# one-liner style
[item1, item2, item3]

# multi-line style
- item1
- item2
- item3

XML

<items>
  <item>item1</item>
  <item>item2</item>
  <item>item3</item>
</items>

Todo

CONFIG:: Needs documentation for Sequences

Configuration

A Configuration represents the whole configuration (file) made of sequences, dictionaries and scalar information items.

JSON

{ "version": "1.0",
  "settings": {
    "key1": "item1",
    "key2": "item2"
  },
  "files": [
    "path/to/file1.ext",
    "path/to/file2.ext",
    "path/to/file3.ext"
  ]
}

TOML

Attention

Not yet implemented.

version = "1.0"

[settings]
key1 = "item1"
key2 = "item2"

files = [
  "path/to/file1.ext",
  "path/to/file2.ext",
  "path/to/file3.ext"
]

YAML

version: "1.0"
settings:
  key1: item1
  key2: item2
files:
  - path/to/file1.ext
  - path/to/file2.ext
  - path/to/file3.ext

XML

Attention

Not yet implemented.

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<configuration version="1.0">
  <settings>
    <setting key="key1">item1</setting>
    <setting key="key2">item2</setting>
  </settings>
  <files>
    <file>path/to/file1.ext</file>
    <file>path/to/file2.ext</file>
    <file>path/to/file3.ext</file>
  </files>
</configuration>

Todo

CONFIG:: Needs documentation for Configuration

Data Model

Todo

CONFIG:: Needs documentation for Data Model

flowchart TD Configuration --> Dictionary Configuration --> Sequence Dictionary --> Dictionary Sequence --> Sequence Dictionary --> Sequence Sequence --> Dictionary

Creating a Concrete Implementation

Follow these steps to derive a concrete implementation of the abstract configuration data model.

1. Import classes from abstract data model

   from . import (
     Node as Abstract_Node,
     Dictionary as Abstract_Dict,
     Sequence as Abstract_Seq,
     Configuration as Abstract_Configuration,
     KeyT, NodeT, ValueT
   )
   

2. Derive a node, which might hold references to nodes in the source file’s parser for later usage.

   @export
   class Node(Abstract_Node):
     _configNode: Union[CommentedMap, CommentedSeq]
     # further local fields
   
     def __init__(self, root: "Configuration", parent: NodeT, key: KeyT, configNode: Union[CommentedMap, CommentedSeq]) -> None:
       Abstract_Node.__init__(self, root, parent)
   
       self._configNode = configNode
   
     # Implement mandatory methods and properties
   

3. Derive a dictionary class:

   @export
   class Dictionary(Node, Abstract_Dict):
     def __init__(self, root: "Configuration", parent: NodeT, key: KeyT, configNode: CommentedMap) -> None:
       Node.__init__(self, root, parent, key, configNode)
   
     # Implement mandatory methods and properties
   

4. Derive a sequence class:

   @export
   class Sequence(Node, Abstract_Seq):
     def __init__(self, root: "Configuration", parent: NodeT, key: KeyT, configNode: CommentedSeq) -> None:
       Node.__init__(self, root, parent, key, configNode)
   
     # Implement mandatory methods and properties
   

5. Set new dictionary and sequence classes as types in the abstract node class.

   setattr(Abstract_Node, "DICT_TYPE", Dictionary)
   setattr(Abstract_Node, "SEQ_TYPE", Sequence)
   

6. Derive a configuration class:

   @export
   class Configuration(Dictionary, Abstract_Configuration):
     def __init__(self, configFile: Path) -> None:
       with configFile.open() as file:
         self._config = ...
   
       Dictionary.__init__(self, self, self, None, self._config)
   
     # Implement mandatory methods and properties