Skip to content

config

frequenz.sdk.config ¤

Config interface.

Classes¤

frequenz.sdk.config.Config ¤

Stores config variables.

Config variables are read from a file. Only single file can be read. If new file is read, then previous configs will be forgotten.

Source code in frequenz/sdk/config/_config.py 
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
class Config:
    """
    Stores config variables.

    Config variables are read from a file.
    Only single file can be read.
    If new file is read, then previous configs will be forgotten.
    """

    def __init__(self, conf_vars: Dict[str, Any]):
        """Instantiate the config store and read config variables from the file.

        Args:
            conf_vars: Dict containing configuration variables
        """
        self._conf_store: Dict[str, Any] = conf_vars

    def get(self, key: str, default: Any = None) -> Any:
        """Get the value for the specified key.

        If the key is not in the configs, then return default.

        Args:
            key: Key to be searched.
            default: Value to be returned if the key is not found.  Defaults to
                None.

        Returns:
            value in str format or default.
        """
        return self._conf_store.get(key, default)

    def get_dict(
        self, key_prefix: str, expected_values_type: Optional[T]
    ) -> Dict[str, Any]:
        """Get a dictionary based on config key prefixes.

        For example, if key_prefix is "my_dict", then the following config store:
            {
                'some_key': 'some_value',
                'my_dict_key1': 'value1',
                'my_dict_key2': 'value2',
            }
        Will return:
            {
                'key1': 'value1',
                'key2': 'value2',
            }

        Args:
            key_prefix: Only get configuration variables starting with this
                prefix.
            expected_values_type: If provided, the value will be validated against
                this type.

        Returns:
            A dictionary containing the keys prefixed with `key_prefix` as keys
                (but with the prefix removed) and the values as values.
        """
        result: Dict[str, Any] = {}
        for key, value in self._conf_store.items():
            if key.startswith(key_prefix):
                new_key = key[len(key_prefix) :]
                if expected_values_type is not None:
                    value = self.get_as(key, expected_values_type)
                result[new_key] = value
        return result

    def get_as(self, key: str, expected_type: Any) -> Any:
        """Get and convert the value to specified type.

        Check if type of the value is as expected.  If type is correct, then
        return converted value.  Otherwise Raise ValueError.

        Type can be:
            * Any typing module type.
            * Any pydantic strict types (e.g. pydantic.StrictInt)

        Args:
            key: Key to be search
            expected_type: type for the value

        Raises:
            ValueError: If can't convert value to the expected type.
            KeyError: If specified key is not in config.

        Returns:
            Value for the specified key, converted to specified type.

        Example:
            For `var1='[1, 2.0, 3.5]'`:
                * `get_as("var1", List[int])` -> `[1,2,3]`
                * `get_as("var1", List[float])` -> `[1.0,2.0,3.5]`
                * `get_as("var1", List[pydantic.StrictInt])` -> [ValueError][]
                * `get_as("var1", List[pydantic.StrictFloat])` -> [ValueError][]

            For `var1='[1,2,3]'`:
                * `get_as("var1", List[pydantic.StrictInt])` -> `[1,2,3]`

        """
        value = self[key]

        if str is expected_type:
            return value

        try:
            parsed_value: Any = parse_raw_as(expected_type, value)
        except (ValidationError, ValueError) as err:
            raise ValueError(
                f"Could not convert config variable: {key} = '{value}' "
                f"to type {str(expected_type)}, err:" + str(err)
            ) from err

        return parsed_value

    def __getitem__(self, key: str) -> Any:
        """Get the value for the specified key.

        If the key is not in the configs, then raise KeyError.

        Args:
            key: key to be searched.

        Raises:
            KeyError: If key is not in found.

        Returns:
            Dictionary if the corresponding value is a subsection in the .toml
                file or a primitive type it is a simple value.
        """
        value = self._conf_store.get(key, None)
        if value is None:
            raise KeyError(f"Unknown config name {key}")

        return value

    def __contains__(self, key: str) -> bool:
        """Return whether the specified key is in the storage.

        Args:
            key: Config variable name.

        Returns:
            True if key is in the storage, otherwise returns False.
        """
        return key in self._conf_store
Functions¤
__contains__(key) ¤

Return whether the specified key is in the storage.

PARAMETER DESCRIPTION
key

Config variable name.

TYPE: str

RETURNS DESCRIPTION
bool

True if key is in the storage, otherwise returns False.
Source code in frequenz/sdk/config/_config.py 
153
154
155
156
157
158
159
160
161
162
def __contains__(self, key: str) -> bool:
    """Return whether the specified key is in the storage.

    Args:
        key: Config variable name.

    Returns:
        True if key is in the storage, otherwise returns False.
    """
    return key in self._conf_store
__getitem__(key) ¤

Get the value for the specified key.

If the key is not in the configs, then raise KeyError.

PARAMETER DESCRIPTION
key

key to be searched.

TYPE: str

RAISES DESCRIPTION
KeyError

If key is not in found.
RETURNS DESCRIPTION
Any

Dictionary if the corresponding value is a subsection in the .toml file or a primitive type it is a simple value.
Source code in frequenz/sdk/config/_config.py 
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
def __getitem__(self, key: str) -> Any:
    """Get the value for the specified key.

    If the key is not in the configs, then raise KeyError.

    Args:
        key: key to be searched.

    Raises:
        KeyError: If key is not in found.

    Returns:
        Dictionary if the corresponding value is a subsection in the .toml
            file or a primitive type it is a simple value.
    """
    value = self._conf_store.get(key, None)
    if value is None:
        raise KeyError(f"Unknown config name {key}")

    return value
__init__(conf_vars) ¤

Instantiate the config store and read config variables from the file.

PARAMETER DESCRIPTION
conf_vars

Dict containing configuration variables

TYPE: Dict[str, Any]

Source code in frequenz/sdk/config/_config.py 
26
27
28
29
30
31
32
def __init__(self, conf_vars: Dict[str, Any]):
    """Instantiate the config store and read config variables from the file.

    Args:
        conf_vars: Dict containing configuration variables
    """
    self._conf_store: Dict[str, Any] = conf_vars
get(key, default=None) ¤

Get the value for the specified key.

If the key is not in the configs, then return default.

PARAMETER DESCRIPTION
key

Key to be searched.

TYPE: str

default

Value to be returned if the key is not found. Defaults to None.

TYPE: Any DEFAULT: None

RETURNS DESCRIPTION
Any

value in str format or default.
Source code in frequenz/sdk/config/_config.py 
34
35
36
37
38
39
40
41
42
43
44
45
46
47
def get(self, key: str, default: Any = None) -> Any:
    """Get the value for the specified key.

    If the key is not in the configs, then return default.

    Args:
        key: Key to be searched.
        default: Value to be returned if the key is not found.  Defaults to
            None.

    Returns:
        value in str format or default.
    """
    return self._conf_store.get(key, default)
get_as(key, expected_type) ¤

Get and convert the value to specified type.

Check if type of the value is as expected. If type is correct, then return converted value. Otherwise Raise ValueError.

Type can be
  • Any typing module type.
  • Any pydantic strict types (e.g. pydantic.StrictInt)
PARAMETER DESCRIPTION
key

Key to be search

TYPE: str

expected_type

type for the value

TYPE: Any

RAISES DESCRIPTION
ValueError

If can't convert value to the expected type.
KeyError

If specified key is not in config.
RETURNS DESCRIPTION
Any

Value for the specified key, converted to specified type.
Example

For var1='[1, 2.0, 3.5]': * get_as("var1", List[int]) -> [1,2,3] * get_as("var1", List[float]) -> [1.0,2.0,3.5] * get_as("var1", List[pydantic.StrictInt]) -> ValueError * get_as("var1", List[pydantic.StrictFloat]) -> ValueError

For var1='[1,2,3]': * get_as("var1", List[pydantic.StrictInt]) -> [1,2,3]

Source code in frequenz/sdk/config/_config.py 
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
def get_as(self, key: str, expected_type: Any) -> Any:
    """Get and convert the value to specified type.

    Check if type of the value is as expected.  If type is correct, then
    return converted value.  Otherwise Raise ValueError.

    Type can be:
        * Any typing module type.
        * Any pydantic strict types (e.g. pydantic.StrictInt)

    Args:
        key: Key to be search
        expected_type: type for the value

    Raises:
        ValueError: If can't convert value to the expected type.
        KeyError: If specified key is not in config.

    Returns:
        Value for the specified key, converted to specified type.

    Example:
        For `var1='[1, 2.0, 3.5]'`:
            * `get_as("var1", List[int])` -> `[1,2,3]`
            * `get_as("var1", List[float])` -> `[1.0,2.0,3.5]`
            * `get_as("var1", List[pydantic.StrictInt])` -> [ValueError][]
            * `get_as("var1", List[pydantic.StrictFloat])` -> [ValueError][]

        For `var1='[1,2,3]'`:
            * `get_as("var1", List[pydantic.StrictInt])` -> `[1,2,3]`

    """
    value = self[key]

    if str is expected_type:
        return value

    try:
        parsed_value: Any = parse_raw_as(expected_type, value)
    except (ValidationError, ValueError) as err:
        raise ValueError(
            f"Could not convert config variable: {key} = '{value}' "
            f"to type {str(expected_type)}, err:" + str(err)
        ) from err

    return parsed_value
get_dict(key_prefix, expected_values_type) ¤

Get a dictionary based on config key prefixes.

For example, if key_prefix is "my_dict", then the following config store: { 'some_key': 'some_value', 'my_dict_key1': 'value1', 'my_dict_key2': 'value2', } Will return: { 'key1': 'value1', 'key2': 'value2', }

PARAMETER DESCRIPTION
key_prefix

Only get configuration variables starting with this prefix.

TYPE: str

expected_values_type

If provided, the value will be validated against this type.

TYPE: Optional[T]

RETURNS DESCRIPTION
Dict[str, Any]

A dictionary containing the keys prefixed with key_prefix as keys (but with the prefix removed) and the values as values.
Source code in frequenz/sdk/config/_config.py 
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
def get_dict(
    self, key_prefix: str, expected_values_type: Optional[T]
) -> Dict[str, Any]:
    """Get a dictionary based on config key prefixes.

    For example, if key_prefix is "my_dict", then the following config store:
        {
            'some_key': 'some_value',
            'my_dict_key1': 'value1',
            'my_dict_key2': 'value2',
        }
    Will return:
        {
            'key1': 'value1',
            'key2': 'value2',
        }

    Args:
        key_prefix: Only get configuration variables starting with this
            prefix.
        expected_values_type: If provided, the value will be validated against
            this type.

    Returns:
        A dictionary containing the keys prefixed with `key_prefix` as keys
            (but with the prefix removed) and the values as values.
    """
    result: Dict[str, Any] = {}
    for key, value in self._conf_store.items():
        if key.startswith(key_prefix):
            new_key = key[len(key_prefix) :]
            if expected_values_type is not None:
                value = self.get_as(key, expected_values_type)
            result[new_key] = value
    return result