ConfZ Configuration Management

ConfZ uses ConfigSource objects to instruct Loader instances on how to retrieve configuration data. You can use several built-in source types depending on your requirements:

• FileSource: Loads data from files. Supports yaml, json, and toml formats. The filename can be provided directly, via an environment variable, or via a command line argument.
• EnvSource: Loads data from environment variables and .env files. You can filter variables using allow-lists or deny-lists, apply an optional prefix, and define a custom separator for nested variables. Variable names can be inferred from the config name or explicitly mapped.
• CLArgSource: Loads data from command line arguments. Supports an optional prefix and custom separators for nested arguments. Argument names can be inferred or explicitly mapped.
• DataSource: Defines constant configuration data. This is particularly useful for providing static values during unit tests.

If you need to override configuration values temporarily—for example during unit tests—you cannot directly modify the CONFIG_SOURCES class variable. Instead, use the change_config_sources context manager provided by your BaseConfig subclass.

When entering the context, the manager backs up the existing configuration source definition and the singleton instance, replaces them with the new source, and deletes the old instance. Upon exiting the context, it restores the original configuration source and singleton instance exactly as they were.

from confz import BaseConfig, FileSource, DataSource

class MyConfig(BaseConfig):
    number: int
    CONFIG_SOURCES = FileSource(file="/path/to/config.yml")

# Temporarily override with a DataSource
new_source = DataSource(data={"number": 42})
with MyConfig.change_config_sources(new_source):
    print(MyConfig().number)  # Output: 42

# Automatically reverts to original source
print(MyConfig().number)  # Output: 1

ConfZ allows you to define multiple sources for your configuration. You can use a single source or a list of sources to combine data from different origins like files, environment variables, and command-line arguments.

Environment-based file selection

Use folder and file_from_env to pick a config file based on an environment variable:

CONFIG_SOURCES = FileSource(
    folder='/path/to/config/folder',
    file_from_env='ENVIRONMENT'
)

Combining Environment and CLI arguments

You can provide a list of sources. For example, to read from a .env file and then override with command-line arguments:

from confz import BaseConfig, EnvSource, CLArgSource

class MyConfig(BaseConfig):
    CONFIG_SOURCES = [
        EnvSource(allow_all=True, file=".env.local"),
        CLArgSource(prefix='conf_')
    ]

Note: For CLArgSource with prefix conf_, a nested attribute like db.user can be set via the command line argument --conf_db.user.

from confz import BaseConfig, EnvSource, CLArgSource

class MyConfig(BaseConfig):
    # ... fields ...
    CONFIG_SOURCES = [
        EnvSource(allow_all=True, file=".env.local"),
        CLArgSource(prefix='conf_')
    ]

ConfZ is modular, allowing you to define and register your own ConfigSource and Loader to inject dynamic data into your configuration.

To extend ConfZ, follow these steps:

1. Define a ConfigSource: Create a dataclass inheriting from ConfigSource. The fields in this class represent the keys that will be written into your configuration dictionary.
2. Define a Loader: Create a class inheriting from Loader. Implement the @classmethod populate_config(cls, config: dict, config_source: CustomSource) method. This method receives the current configuration dictionary and your custom source instance. Use cls.update_dict_recursively(config, config_update) to merge new values into the existing config.
3. Register the Loader: Use register_loader(CustomSource, CustomLoader) to link your source to your loader.
4. Use the Source: Pass an instance of your CustomSource to the config_sources argument of any BaseConfig class.

import sys
from dataclasses import dataclass
from confz import ConfigSource, BaseConfig, register_loader
from confz.loaders import Loader

# 1. Define the source
@dataclass
class CustomSource(ConfigSource):
    platform: str = None    # The value of this field will be the key in the config
    version: str = None     # The value of this field will be the key in the config

# 2. Define the loader
class CustomLoader(Loader):
    @classmethod
    def populate_config(cls, config: dict, config_source: CustomSource):
        config_update = {
            config_source.platform: sys.platform,
            config_source.version: f"{sys.version_info[0]}.{sys.version_info[1]}"
        }
        cls.update_dict_recursively(config, config_update)

# 3. Register
register_loader(CustomSource, CustomLoader)

# 4. Use in a config class
class MyConfig(BaseConfig):
    attr1: str
    attr2: str

config = MyConfig(config_sources=CustomSource(
    platform="attr1",
    version="attr2"
))
print(config)
# Output: MyConfig(attr1='win32' attr2='3.9')