Skip to content

Module API - Loaders

superconf.loaders

Loaders library

AbstractConfigurationLoader

Abstract base class for configuration loaders.

This class defines the interface that all configuration loaders must implement. Configuration loaders are responsible for loading configuration values from different sources (files, environment, etc.).

Source code in superconf/loaders.py 
 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
class AbstractConfigurationLoader:
    """
    Abstract base class for configuration loaders.

    This class defines the interface that all configuration loaders must implement.
    Configuration loaders are responsible for loading configuration values from
    different sources (files, environment, etc.).
    """

    def __repr__(self):
        raise NotImplementedError()  # pragma: no cover

    def __contains__(self, item):
        """Check if a configuration key exists in this loader."""
        raise NotImplementedError()  # pragma: no cover

    def __getitem__(self, item):
        """Retrieve a configuration value by key."""
        raise NotImplementedError()  # pragma: no cover

    def check(self):
        """
        Verify if the configuration source is valid and accessible.

        Returns:
            bool: True if the configuration source is valid, False otherwise.
        """
        return True

    def reset(self):
        """Reset the loader's internal state."""

    # pylint: disable=unused-argument
    def contains(self, config, item):
        """
        Check if a configuration key exists in this loader.

        Args:
            config: The configuration object.
            item (str): The configuration key to check.

        Returns:
            bool: True if the key exists, False otherwise.
        """
        return self.__contains__(item)
        # raise NotImplementedError()  # pragma: no cover

    def getitem(self, config, item):
        """
        Retrieve a configuration value by key.

        Args:
            config: The configuration object.
            item (str): The configuration key to retrieve.

        Returns:
            The configuration value for the given key.

        Raises:
            KeyError: If the key doesn't exist.
        """
        return self.__getitem__(item)

__contains__(item)

Check if a configuration key exists in this loader.

Source code in superconf/loaders.py 
77
78
79
def __contains__(self, item):
    """Check if a configuration key exists in this loader."""
    raise NotImplementedError()  # pragma: no cover

__getitem__(item)

Retrieve a configuration value by key.

Source code in superconf/loaders.py 
81
82
83
def __getitem__(self, item):
    """Retrieve a configuration value by key."""
    raise NotImplementedError()  # pragma: no cover

check()

Verify if the configuration source is valid and accessible.

Returns:

Name Type Description
bool

True if the configuration source is valid, False otherwise.
Source code in superconf/loaders.py 
85
86
87
88
89
90
91
92
def check(self):
    """
    Verify if the configuration source is valid and accessible.

    Returns:
        bool: True if the configuration source is valid, False otherwise.
    """
    return True

contains(config, item)

Check if a configuration key exists in this loader.

Parameters:

Name Type Description Default
config

The configuration object.

 required
item str

The configuration key to check.

 required

Returns:

Name Type Description
bool

True if the key exists, False otherwise.
Source code in superconf/loaders.py 
 98
 99
100
101
102
103
104
105
106
107
108
109
def contains(self, config, item):
    """
    Check if a configuration key exists in this loader.

    Args:
        config: The configuration object.
        item (str): The configuration key to check.

    Returns:
        bool: True if the key exists, False otherwise.
    """
    return self.__contains__(item)

getitem(config, item)

Retrieve a configuration value by key.

Parameters:

Name Type Description Default
config

The configuration object.

 required
item str

The configuration key to retrieve.

 required

Returns:

Type Description

The configuration value for the given key.

Raises:

Type Description
KeyError

If the key doesn't exist.
Source code in superconf/loaders.py 
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
def getitem(self, config, item):
    """
    Retrieve a configuration value by key.

    Args:
        config: The configuration object.
        item (str): The configuration key to retrieve.

    Returns:
        The configuration value for the given key.

    Raises:
        KeyError: If the key doesn't exist.
    """
    return self.__getitem__(item)

reset()

Reset the loader's internal state.

Source code in superconf/loaders.py 
94
95
def reset(self):
    """Reset the loader's internal state."""

CommandLine

Bases: AbstractConfigurationLoader

Configuration loader that extracts settings from command line arguments.

This loader uses an argparse.ArgumentParser to extract configuration values from command line arguments.

Parameters:

Name Type Description Default
parser ArgumentParser

The parser instance to extract variables from.

 required
get_args callable

Optional function to extract args from the parser. Defaults to the get_args function.

 _get_args
Source code in superconf/loaders.py 
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 CommandLine(AbstractConfigurationLoader):
    """
    Configuration loader that extracts settings from command line arguments.

    This loader uses an argparse.ArgumentParser to extract configuration values
    from command line arguments.

    Args:
        parser (argparse.ArgumentParser): The parser instance to extract variables from.
        get_args (callable): Optional function to extract args from the parser.
                           Defaults to the get_args function.
    """

    # noinspection PyShadowingNames
    def __init__(self, parser, get_args=_get_args):
        """
        :param parser: An `argparse` parser instance to extract variables from.
        :param function get_args: A function to extract args from the parser.
        :type parser: argparse.ArgumentParser
        """
        self.parser = parser
        self.configs = get_args(self.parser)

    def __repr__(self):
        return f"{self.__class__.__name__}(parser={self.parser})"

    def __contains__(self, item):
        """Check if a configuration key exists in the parsed arguments."""
        return item in self.configs

    def __getitem__(self, item):
        """Retrieve a configuration value from the parsed arguments."""
        return self.configs[item]

__contains__(item)

Check if a configuration key exists in the parsed arguments.

Source code in superconf/loaders.py 
156
157
158
def __contains__(self, item):
    """Check if a configuration key exists in the parsed arguments."""
    return item in self.configs

__getitem__(item)

Retrieve a configuration value from the parsed arguments.

Source code in superconf/loaders.py 
160
161
162
def __getitem__(self, item):
    """Retrieve a configuration value from the parsed arguments."""
    return self.configs[item]

__init__(parser, get_args=_get_args)

:param parser: An argparse parser instance to extract variables from. :param function get_args: A function to extract args from the parser. :type parser: argparse.ArgumentParser

Source code in superconf/loaders.py 
144
145
146
147
148
149
150
151
def __init__(self, parser, get_args=_get_args):
    """
    :param parser: An `argparse` parser instance to extract variables from.
    :param function get_args: A function to extract args from the parser.
    :type parser: argparse.ArgumentParser
    """
    self.parser = parser
    self.configs = get_args(self.parser)

Dict

Bases: AbstractConfigurationLoader

Configuration loader that uses a dictionary as the configuration source.

This loader is useful for providing hardcoded default values or for testing.

Parameters:

Name Type Description Default
values_mapping dict

A dictionary of configuration key-value pairs.

 required
Example

config = Dict({"debug": "true", "port": "8000"}) "debug" in config # True config["port"] # "8000"

Source code in superconf/loaders.py 
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
class Dict(AbstractConfigurationLoader):
    """
    Configuration loader that uses a dictionary as the configuration source.

    This loader is useful for providing hardcoded default values or for testing.

    Args:
        values_mapping (dict): A dictionary of configuration key-value pairs.

    Example:
        >>> config = Dict({"debug": "true", "port": "8000"})
        >>> "debug" in config  # True
        >>> config["port"]  # "8000"
    """

    def __init__(self, values_mapping):
        self.values_mapping = values_mapping

    def __repr__(self):
        return f"{self.__class__.__name__}({self.values_mapping})"

    def __contains__(self, item):
        """Check if a configuration key exists in the dictionary."""
        return item in self.values_mapping

    def __getitem__(self, item):
        """
        Retrieve a configuration value from the dictionary.

        Args:
            item (str): The configuration key to retrieve.

        Returns:
            The configuration value.

        Raises:
            KeyError: If the key doesn't exist in the dictionary.
        """
        return self.values_mapping[item]

__contains__(item)

Check if a configuration key exists in the dictionary.

Source code in superconf/loaders.py 
676
677
678
def __contains__(self, item):
    """Check if a configuration key exists in the dictionary."""
    return item in self.values_mapping

__getitem__(item)

Retrieve a configuration value from the dictionary.

Parameters:

Name Type Description Default
item str

The configuration key to retrieve.

 required

Returns:

Type Description

The configuration value.

Raises:

Type Description
KeyError

If the key doesn't exist in the dictionary.
Source code in superconf/loaders.py 
680
681
682
683
684
685
686
687
688
689
690
691
692
693
def __getitem__(self, item):
    """
    Retrieve a configuration value from the dictionary.

    Args:
        item (str): The configuration key to retrieve.

    Returns:
        The configuration value.

    Raises:
        KeyError: If the key doesn't exist in the dictionary.
    """
    return self.values_mapping[item]

EnvFile

Bases: AbstractConfigurationLoader

Configuration loader that reads settings from a .env file.

This loader reads configuration values from a file in environment variable format (KEY=value).

Parameters:

Name Type Description Default
filename str

Path to the .env file. Defaults to ".env".

 '.env'
keyfmt callable

Optional function to pre-format variable names. Defaults to EnvPrefix() which converts keys to uppercase.

 EnvPrefix()
Example

env = EnvFile(".env", keyfmt=EnvPrefix("MYAPP_"))

With .env containing: DEBUG=true

"debug" in env

Returns True

env["debug"]

Return "true"

Source code in superconf/loaders.py 
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
class EnvFile(AbstractConfigurationLoader):
    """
    Configuration loader that reads settings from a .env file.

    This loader reads configuration values from a file in environment variable
    format (KEY=value).

    Args:
        filename (str): Path to the .env file. Defaults to ".env".
        keyfmt (callable): Optional function to pre-format variable names.
                          Defaults to EnvPrefix() which converts keys to uppercase.

    Example:
        >>> env = EnvFile(".env", keyfmt=EnvPrefix("MYAPP_"))

        With .env containing: DEBUG=true

        >>> "debug" in env

        Returns `True`

        >>> env["debug"]

        Return `"true"`
    """

    def __init__(self, filename=".env", keyfmt=EnvPrefix()):
        self.filename = filename
        self.keyfmt = keyfmt
        self.configs = None

    def __repr__(self):
        return f'{self.__class__.__name__}("{self.filename}")'

    def _parse(self):
        """
        Parse the .env file if not already parsed.

        Raises:
            FileNotFoundError: If the file doesn't exist or can't be read.
        """
        if self.configs is not None:
            return

        self.configs = {}
        with open(self.filename, encoding="utf-8") as envfile:
            self.configs.update(EnvFileParser(envfile).parse_config())

    def check(self):
        """
        Verify if the .env file exists and is valid.

        Returns:
            bool: True if the file exists and is valid, False otherwise.
        """
        if not os.path.isfile(self.filename):
            return False

        try:
            self._parse()
        except FileNotFoundError:
            return False

        return super().check()

    def __contains__(self, item):
        """Check if a configuration key exists in the .env file."""
        if not self.check():
            return False

        return self.keyfmt(item) in self.configs

    def __getitem__(self, item):
        """
        Retrieve a configuration value from the .env file.

        Args:
            item (str): The configuration key to retrieve.

        Returns:
            str: The configuration value.

        Raises:
            KeyError: If the key doesn't exist in the file.
        """
        if not self.check():
            raise KeyError(f"{item}")

        return self.configs[self.keyfmt(item)]

    def reset(self):
        """Reset the parsed configuration cache."""
        self.configs = None

__contains__(item)

Check if a configuration key exists in the .env file.

Source code in superconf/loaders.py 
456
457
458
459
460
461
def __contains__(self, item):
    """Check if a configuration key exists in the .env file."""
    if not self.check():
        return False

    return self.keyfmt(item) in self.configs

__getitem__(item)

Retrieve a configuration value from the .env file.

Parameters:

Name Type Description Default
item str

The configuration key to retrieve.

 required

Returns:

Name Type Description
str

The configuration value.

Raises:

Type Description
KeyError

If the key doesn't exist in the file.
Source code in superconf/loaders.py 
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
def __getitem__(self, item):
    """
    Retrieve a configuration value from the .env file.

    Args:
        item (str): The configuration key to retrieve.

    Returns:
        str: The configuration value.

    Raises:
        KeyError: If the key doesn't exist in the file.
    """
    if not self.check():
        raise KeyError(f"{item}")

    return self.configs[self.keyfmt(item)]

check()

Verify if the .env file exists and is valid.

Returns:

Name Type Description
bool

True if the file exists and is valid, False otherwise.
Source code in superconf/loaders.py 
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
def check(self):
    """
    Verify if the .env file exists and is valid.

    Returns:
        bool: True if the file exists and is valid, False otherwise.
    """
    if not os.path.isfile(self.filename):
        return False

    try:
        self._parse()
    except FileNotFoundError:
        return False

    return super().check()

reset()

Reset the parsed configuration cache.

Source code in superconf/loaders.py 
481
482
483
def reset(self):
    """Reset the parsed configuration cache."""
    self.configs = None

EnvPrefix

A utility class for namespacing environment variables with a prefix.

Since the environment is a global dictionary, it is a good practice to namespace your settings by using a unique prefix like MY_APP_.

Parameters:

Name Type Description Default
prefix str

The prefix to prepend to environment variable names. Defaults to "".

 ''
Example

prefix = EnvPrefix("MYAPP_") prefix("database_url") 'MYAPP_DATABASE_URL'

Source code in superconf/loaders.py 
15
16
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
class EnvPrefix:
    """
    A utility class for namespacing environment variables with a prefix.

    Since the environment is a global dictionary, it is a good practice to
    namespace your settings by using a unique prefix like ``MY_APP_``.

    Args:
        prefix (str): The prefix to prepend to environment variable names. Defaults to "".

    Example:
        >>> prefix = EnvPrefix("MYAPP_")
        >>> prefix("database_url")
        'MYAPP_DATABASE_URL'
    """

    def __init__(self, prefix=""):
        self.prefix = prefix

    def __call__(self, value):
        """
        Transform a configuration key into an environment variable name.

        Args:
            value (str): The configuration key to transform.

        Returns:
            str: The environment variable name with the prefix applied and converted to uppercase.
        """
        value = str(value)
        return f"{self.prefix}{value.upper()}"

    def __repr__(self):
        return f'{self.__class__.__name__}("{self.prefix}")'

__call__(value)

Transform a configuration key into an environment variable name.

Parameters:

Name Type Description Default
value str

The configuration key to transform.

 required

Returns:

Name Type Description
str

The environment variable name with the prefix applied and converted to uppercase.
Source code in superconf/loaders.py 
34
35
36
37
38
39
40
41
42
43
44
45
def __call__(self, value):
    """
    Transform a configuration key into an environment variable name.

    Args:
        value (str): The configuration key to transform.

    Returns:
        str: The environment variable name with the prefix applied and converted to uppercase.
    """
    value = str(value)
    return f"{self.prefix}{value.upper()}"

Environment

Bases: AbstractConfigurationLoader

Configuration loader that reads settings from environment variables.

This loader retrieves configuration values from the system's environment variables (os.environ), optionally transforming the keys using a formatting function.

Parameters:

Name Type Description Default
keyfmt callable

Optional function to pre-format variable names. Defaults to EnvPrefix() which converts keys to uppercase.

 EnvPrefix()
Example

env = Environment(keyfmt=EnvPrefix("MYAPP_")) os.environ["MYAPP_DEBUG"] = "true" "debug" in env # True env["debug"] # "true"

Source code in superconf/loaders.py 
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
class Environment(AbstractConfigurationLoader):
    """
    Configuration loader that reads settings from environment variables.

    This loader retrieves configuration values from the system's environment
    variables (os.environ), optionally transforming the keys using a formatting
    function.

    Args:
        keyfmt (callable): Optional function to pre-format variable names.
                          Defaults to EnvPrefix() which converts keys to uppercase.

    Example:
        >>> env = Environment(keyfmt=EnvPrefix("MYAPP_"))
        >>> os.environ["MYAPP_DEBUG"] = "true"
        >>> "debug" in env  # True
        >>> env["debug"]  # "true"
    """

    def __init__(self, keyfmt=EnvPrefix(), prefix: str = None, sep: str = "__"):
        """
        :param function keyfmt: A function to pre-format variable names.
        """
        self.keyfmt = keyfmt
        self.prefix = prefix
        self.sep = sep

    def __repr__(self):
        return f"{self.__class__.__name__}(keyfmt={self.keyfmt})"

    def __contains__(self, item: str) -> bool:
        """Check if an environment variable exists for the given key."""
        return self.keyfmt(item) in os.environ

    def __getitem__(self, item: str):
        """
        Retrieve a configuration value from environment variables.

        Args:
            item (str): The configuration key to retrieve.

        Returns:
            str: The environment variable value.

        Raises:
            KeyError: If the environment variable doesn't exist.
        """
        return os.environ[self.keyfmt(item)]

    def get_env_name(self, config, item: str) -> str:
        "Return the envirnonment name for a given key in config"

        # Check if environment is enabled, and parents
        pkey_enabled = config.query_inst_cfg("env_enabled", default=True)
        parents = []
        if pkey_enabled:
            parents = config.get_hierarchy()  # [:-1]

        # For each parents, from bottom to top
        parents_keys = []
        for parent in parents:

            # Fetch pkey info
            pkey = parent.query_inst_cfg("env_name", default=parent.key)
            pkey_prefix = parent.query_inst_cfg("env_prefix", default="")
            pkey_pattern = parent.query_inst_cfg("env_pattern", default="{prefix}{key}")

            # Check if root:
            pkey_prefix = pkey_prefix or ""
            # pylint: disable=protected-access
            if parent._parent is None and pkey is None:
                # Is probably root, then we have to guess the name if not explicit
                pkey = ""
                if not pkey_prefix:
                    pkey = parent.__class__.__name__
                    pkey_prefix = ""

            # Render format
            pfinal = pkey_pattern.format(
                prefix=pkey_prefix,
                key=pkey,
            )
            pfinal = [str(x) for x in [pkey_prefix, pkey] if x]
            pfinal = "_".join(pfinal)
            parents_keys.append(pfinal)

            # Quit if object does not want parents
            pkey_parents = parent.query_inst_cfg("env_parents", default=True)
            if pkey_parents is False:
                break

        # Reverse key order, from top to bottom, transform to string, and then uppsercase
        parents_keys = list(reversed(parents_keys))
        parents_keys.append(item)
        parents_keys = [str(x) for x in parents_keys if x]
        # print(parents_keys)
        fkey = self.sep.join(parents_keys).upper()

        return fkey

    def getitem(self, config, item: str):
        """
        Retrieve a configuration value by key.

        Args:
            config: The configuration object.
            item (str): The configuration key to retrieve.

        Returns:
            The configuration value for the given key.

        Raises:
            KeyError: If the key doesn't exist.
        """

        fkey = self.get_env_name(config, item)
        # print("==== LOOK  ENV", fkey)
        ret = os.environ[fkey]
        # print("==== FOUND ENV", fkey, "=", ret)

        ret = os.path.expandvars(ret)
        ret = os.path.expanduser(ret)
        return ret

__contains__(item)

Check if an environment variable exists for the given key.

Source code in superconf/loaders.py 
293
294
295
def __contains__(self, item: str) -> bool:
    """Check if an environment variable exists for the given key."""
    return self.keyfmt(item) in os.environ

__getitem__(item)

Retrieve a configuration value from environment variables.

Parameters:

Name Type Description Default
item str

The configuration key to retrieve.

 required

Returns:

Name Type Description
str

The environment variable value.

Raises:

Type Description
KeyError

If the environment variable doesn't exist.
Source code in superconf/loaders.py 
297
298
299
300
301
302
303
304
305
306
307
308
309
310
def __getitem__(self, item: str):
    """
    Retrieve a configuration value from environment variables.

    Args:
        item (str): The configuration key to retrieve.

    Returns:
        str: The environment variable value.

    Raises:
        KeyError: If the environment variable doesn't exist.
    """
    return os.environ[self.keyfmt(item)]

__init__(keyfmt=EnvPrefix(), prefix=None, sep='__')

:param function keyfmt: A function to pre-format variable names.

Source code in superconf/loaders.py 
282
283
284
285
286
287
288
def __init__(self, keyfmt=EnvPrefix(), prefix: str = None, sep: str = "__"):
    """
    :param function keyfmt: A function to pre-format variable names.
    """
    self.keyfmt = keyfmt
    self.prefix = prefix
    self.sep = sep

get_env_name(config, item)

Return the envirnonment name for a given key in config

Source code in superconf/loaders.py 
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
def get_env_name(self, config, item: str) -> str:
    "Return the envirnonment name for a given key in config"

    # Check if environment is enabled, and parents
    pkey_enabled = config.query_inst_cfg("env_enabled", default=True)
    parents = []
    if pkey_enabled:
        parents = config.get_hierarchy()  # [:-1]

    # For each parents, from bottom to top
    parents_keys = []
    for parent in parents:

        # Fetch pkey info
        pkey = parent.query_inst_cfg("env_name", default=parent.key)
        pkey_prefix = parent.query_inst_cfg("env_prefix", default="")
        pkey_pattern = parent.query_inst_cfg("env_pattern", default="{prefix}{key}")

        # Check if root:
        pkey_prefix = pkey_prefix or ""
        # pylint: disable=protected-access
        if parent._parent is None and pkey is None:
            # Is probably root, then we have to guess the name if not explicit
            pkey = ""
            if not pkey_prefix:
                pkey = parent.__class__.__name__
                pkey_prefix = ""

        # Render format
        pfinal = pkey_pattern.format(
            prefix=pkey_prefix,
            key=pkey,
        )
        pfinal = [str(x) for x in [pkey_prefix, pkey] if x]
        pfinal = "_".join(pfinal)
        parents_keys.append(pfinal)

        # Quit if object does not want parents
        pkey_parents = parent.query_inst_cfg("env_parents", default=True)
        if pkey_parents is False:
            break

    # Reverse key order, from top to bottom, transform to string, and then uppsercase
    parents_keys = list(reversed(parents_keys))
    parents_keys.append(item)
    parents_keys = [str(x) for x in parents_keys if x]
    # print(parents_keys)
    fkey = self.sep.join(parents_keys).upper()

    return fkey

getitem(config, item)

Retrieve a configuration value by key.

Parameters:

Name Type Description Default
config

The configuration object.

 required
item str

The configuration key to retrieve.

 required

Returns:

Type Description

The configuration value for the given key.

Raises:

Type Description
KeyError

If the key doesn't exist.
Source code in superconf/loaders.py 
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
def getitem(self, config, item: str):
    """
    Retrieve a configuration value by key.

    Args:
        config: The configuration object.
        item (str): The configuration key to retrieve.

    Returns:
        The configuration value for the given key.

    Raises:
        KeyError: If the key doesn't exist.
    """

    fkey = self.get_env_name(config, item)
    # print("==== LOOK  ENV", fkey)
    ret = os.environ[fkey]
    # print("==== FOUND ENV", fkey, "=", ret)

    ret = os.path.expandvars(ret)
    ret = os.path.expanduser(ret)
    return ret

IniFile

Bases: AbstractConfigurationLoader

Configuration loader that reads settings from an INI/CFG file.

This loader reads configuration from a specified section in an INI-style configuration file.

Parameters:

Name Type Description Default
filename str

Path to the .ini/.cfg file.

 required
section str

Section name inside the config file. Defaults to "settings".

 'settings'
keyfmt callable

Optional function to pre-format variable names.

 lambda x: x

Raises:

Type Description
InvalidConfigurationFile

If the file is not a valid INI file.
MissingSettingsSection

If the specified section is not found in the file.
Source code in superconf/loaders.py 
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
class IniFile(AbstractConfigurationLoader):
    """
    Configuration loader that reads settings from an INI/CFG file.

    This loader reads configuration from a specified section in an INI-style
    configuration file.

    Args:
        filename (str): Path to the .ini/.cfg file.
        section (str): Section name inside the config file. Defaults to "settings".
        keyfmt (callable): Optional function to pre-format variable names.

    Raises:
        InvalidConfigurationFile: If the file is not a valid INI file.
        MissingSettingsSection: If the specified section is not found in the file.
    """

    def __init__(self, filename, section="settings", keyfmt=lambda x: x):
        self.filename = filename
        self.section = section
        self.keyfmt = keyfmt
        self.parser = ConfigParser(allow_no_value=True)
        self._initialized = False

    def __repr__(self):
        return f'{self.__class__.__name__}("{self.filename}")'

    def _parse(self):
        """
        Parse the INI file if not already parsed.

        Raises:
            InvalidConfigurationFile: If the file is not a valid INI file.
            MissingSettingsSection: If the specified section is not found.
        """
        if self._initialized:
            return

        with open(self.filename, encoding="utf-8") as inifile:
            try:
                self.parser.read_file(inifile)
            except (UnicodeDecodeError, MissingSectionHeaderError) as err:
                raise InvalidConfigurationFile() from err

        if not self.parser.has_section(self.section):
            raise MissingSettingsSection(
                f"Missing [{self.section}] section in {self.filename}"
            )

        self._initialized = True

    def check(self):
        """
        Verify if the INI file exists and is valid.

        Returns:
            bool: True if the file exists and is valid, False otherwise.
        """
        try:
            self._parse()
        except (FileNotFoundError, InvalidConfigurationFile, MissingSettingsSection):
            return False

        return super().check()

    def __contains__(self, item):
        """Check if a configuration key exists in the INI file section."""
        if not self.check():
            return False

        return self.parser.has_option(self.section, self.keyfmt(item))

    def __getitem__(self, item):
        """
        Retrieve a configuration value from the INI file section.

        Args:
            item (str): The configuration key to retrieve.

        Returns:
            str: The configuration value.

        Raises:
            KeyError: If the key doesn't exist in the section.
        """
        if not self.check():
            raise KeyError(f"{item}")

        try:
            return self.parser.get(self.section, self.keyfmt(item))
        except NoOptionError as err:
            raise KeyError(f"{item}") from err

    def reset(self):
        """Reset the parser's initialization state."""
        self._initialized = False

__contains__(item)

Check if a configuration key exists in the INI file section.

Source code in superconf/loaders.py 
230
231
232
233
234
235
def __contains__(self, item):
    """Check if a configuration key exists in the INI file section."""
    if not self.check():
        return False

    return self.parser.has_option(self.section, self.keyfmt(item))

__getitem__(item)

Retrieve a configuration value from the INI file section.

Parameters:

Name Type Description Default
item str

The configuration key to retrieve.

 required

Returns:

Name Type Description
str

The configuration value.

Raises:

Type Description
KeyError

If the key doesn't exist in the section.
Source code in superconf/loaders.py 
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
def __getitem__(self, item):
    """
    Retrieve a configuration value from the INI file section.

    Args:
        item (str): The configuration key to retrieve.

    Returns:
        str: The configuration value.

    Raises:
        KeyError: If the key doesn't exist in the section.
    """
    if not self.check():
        raise KeyError(f"{item}")

    try:
        return self.parser.get(self.section, self.keyfmt(item))
    except NoOptionError as err:
        raise KeyError(f"{item}") from err

check()

Verify if the INI file exists and is valid.

Returns:

Name Type Description
bool

True if the file exists and is valid, False otherwise.
Source code in superconf/loaders.py 
216
217
218
219
220
221
222
223
224
225
226
227
228
def check(self):
    """
    Verify if the INI file exists and is valid.

    Returns:
        bool: True if the file exists and is valid, False otherwise.
    """
    try:
        self._parse()
    except (FileNotFoundError, InvalidConfigurationFile, MissingSettingsSection):
        return False

    return super().check()

reset()

Reset the parser's initialization state.

Source code in superconf/loaders.py 
258
259
260
def reset(self):
    """Reset the parser's initialization state."""
    self._initialized = False

RecursiveSearch

Bases: AbstractConfigurationLoader

Configuration loader that recursively searches for configuration files.

This loader looks for configuration files in the current directory and all parent directories up to a specified root path. It supports multiple file types and loaders.

Parameters:

Name Type Description Default
starting_path str

The path to begin looking for configuration files.

 None
filetypes tuple

Tuple of (pattern, loader_class) pairs defining which files to look for and how to load them. Defaults to .env, .ini, and .cfg files.

 (('.env', EnvFile), (('*.ini', '*.cfg'), IniFile))
root_path str

The path where the search will stop. Defaults to "/".

 '/'
Example

search = RecursiveSearch("/home/user/project")

Will look for .env, .ini, and .cfg files in: /home/user/project /home/user /home /

Source code in superconf/loaders.py 
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
class RecursiveSearch(AbstractConfigurationLoader):
    """
    Configuration loader that recursively searches for configuration files.

    This loader looks for configuration files in the current directory and all parent
    directories up to a specified root path. It supports multiple file types and loaders.

    Args:
        starting_path (str, optional): The path to begin looking for configuration files.
        filetypes (tuple): Tuple of (pattern, loader_class) pairs defining which files
                          to look for and how to load them. Defaults to .env, .ini, and .cfg files.
        root_path (str): The path where the search will stop. Defaults to "/".

    Example:
        >>> search = RecursiveSearch("/home/user/project")

        Will look for .env, .ini, and .cfg files in:
        /home/user/project
        /home/user
        /home
        /
    """

    def __init__(
        self,
        starting_path=None,
        filetypes=((".env", EnvFile), (("*.ini", "*.cfg"), IniFile)),
        root_path="/",
    ):
        self.root_path = os.path.realpath(root_path)
        self._starting_path = self.root_path

        if starting_path:
            self.starting_path = starting_path

        self.filetypes = filetypes
        self._config_files = None

    @property
    def starting_path(self):
        """Get the current starting path for the search."""
        return self._starting_path

    @starting_path.setter
    def starting_path(self, path):
        """
        Set the starting path for the search.

        Args:
            path (str): The new starting path.

        Raises:
            InvalidPath: If the path is invalid or outside the root path.
        """
        if not path:
            raise InvalidPath("Invalid starting path")

        path = os.path.realpath(os.path.abspath(path))
        if not path.startswith(self.root_path):
            raise InvalidPath("Invalid root path given")
        self._starting_path = path

    @staticmethod
    def get_filenames(path, patterns):
        """
        Get all filenames in a directory matching the given patterns.

        Args:
            path (str): Directory to search in.
            patterns (str or tuple): Glob pattern(s) to match against.

        Returns:
            list: List of matching filenames.
        """
        filenames = []
        if isinstance(patterns, str):
            patterns = (patterns,)

        for pattern in patterns:
            filenames += glob(os.path.join(path, pattern))
        return filenames

    def _scan_path(self, path):
        """
        Scan a directory for configuration files.

        Args:
            path (str): Directory to scan.

        Returns:
            list: List of configuration loader instances for found files.
        """
        config_files = []

        for patterns, Loader in self.filetypes:
            for filename in self.get_filenames(path, patterns):
                try:
                    loader = Loader(filename=filename)
                    if not loader.check():
                        continue
                    config_files.append(loader)
                except InvalidConfigurationFile:
                    continue

        return config_files

    def _discover(self):
        """Discover all configuration files in the search path hierarchy."""
        self._config_files = []

        path = self.starting_path
        while True:
            if os.path.isdir(path):
                self._config_files += self._scan_path(path)

            if path == self.root_path:
                break

            path = os.path.dirname(path)

    @property
    def config_files(self):
        """
        Get all discovered configuration files.

        Returns:
            list: List of configuration loader instances.
        """
        if self._config_files is None:
            self._discover()

        return self._config_files

    def __contains__(self, item):
        """Check if a configuration key exists in any of the discovered files."""
        for config_file in self.config_files:
            if item in config_file:
                return True
        return False

    def __getitem__(self, item):
        """
        Retrieve a configuration value from the first file that contains it.

        Args:
            item (str): The configuration key to retrieve.

        Returns:
            str: The configuration value.

        Raises:
            KeyError: If the key doesn't exist in any configuration file.
        """
        for config_file in self.config_files:
            try:
                return config_file[item]
            except KeyError:
                continue

        raise KeyError(f"{item}")

    def __repr__(self):
        return f"{self.__class__.__name__}(root_path={self.root_path})"

    def reset(self):
        """Reset the discovered configuration files cache."""
        self._config_files = None

config_files property

Get all discovered configuration files.

Returns:

Name Type Description
list

List of configuration loader instances.

starting_path property writable

Get the current starting path for the search.

__contains__(item)

Check if a configuration key exists in any of the discovered files.

Source code in superconf/loaders.py 
619
620
621
622
623
624
def __contains__(self, item):
    """Check if a configuration key exists in any of the discovered files."""
    for config_file in self.config_files:
        if item in config_file:
            return True
    return False

__getitem__(item)

Retrieve a configuration value from the first file that contains it.

Parameters:

Name Type Description Default
item str

The configuration key to retrieve.

 required

Returns:

Name Type Description
str

The configuration value.

Raises:

Type Description
KeyError

If the key doesn't exist in any configuration file.
Source code in superconf/loaders.py 
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
def __getitem__(self, item):
    """
    Retrieve a configuration value from the first file that contains it.

    Args:
        item (str): The configuration key to retrieve.

    Returns:
        str: The configuration value.

    Raises:
        KeyError: If the key doesn't exist in any configuration file.
    """
    for config_file in self.config_files:
        try:
            return config_file[item]
        except KeyError:
            continue

    raise KeyError(f"{item}")

get_filenames(path, patterns) staticmethod

Get all filenames in a directory matching the given patterns.

Parameters:

Name Type Description Default
path str

Directory to search in.

 required
patterns str or tuple

Glob pattern(s) to match against.

 required

Returns:

Name Type Description
list

List of matching filenames.
Source code in superconf/loaders.py 
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
@staticmethod
def get_filenames(path, patterns):
    """
    Get all filenames in a directory matching the given patterns.

    Args:
        path (str): Directory to search in.
        patterns (str or tuple): Glob pattern(s) to match against.

    Returns:
        list: List of matching filenames.
    """
    filenames = []
    if isinstance(patterns, str):
        patterns = (patterns,)

    for pattern in patterns:
        filenames += glob(os.path.join(path, pattern))
    return filenames

reset()

Reset the discovered configuration files cache.

Source code in superconf/loaders.py 
650
651
652
def reset(self):
    """Reset the discovered configuration files cache."""
    self._config_files = None