Welcome to ConfigFramework’s documentation!

ConfigFramework

A small and simple framework to build your configs.

This project been created mostly because of me myself needing some simplistic and at the same time powerful enough tool to create configs, validate them through have simple interface.

Installing

Pypi link: https://pypi.org/project/ConfigFramework

Install with command: pip install ConfigFramework

To install with mypy you must use command: pip install ConfigFramework[mypy]

If you have python below 3.11 or need toml format with ability to write it back: pip install ConfigFramework[toml]

To install with mypy and docs building requirements you must use command: pip install ConfigFramework[mypy,docs]

Example of usage

from config_framework import BaseConfig, VariableKey, Variable
from config_framework.loaders import Dict

loader = Dict.load(
    data=dict(
        user_id=1,
        nested_val=dict(pi=3.14)
    )
)


class ConfigSample(BaseConfig):
    user_id: Variable[int] = Variable(VariableKey("user_id"))
    pi_value = Variable(VariableKey("nested_val") / "pi")
    # Defaults only applied when key isn't found.
    # Also default values will be validated after initializing, and after you register new validator.
    some_value = Variable("not_found_value", default="Hello world")

    @staticmethod
    @user_id.register_validator
    def validate_user_id(var, value):
        # Functions can return bool values or raise
        # config_framework.types.custom_exceptions.InvalidValueError
        # for more detailed description.
        return value == 1

    def __post_init__(self) -> None:
        print("Post init here!")
        print("Values aren't locked yet")

        self.new_value = 122


config = ConfigSample(loader)
print("User id:", config.user_id)
print("Pi value:", config.pi_value)
print("Some value:", config.some_value)
print("Post inited value:", config.new_value)

# Configs by default aren't modifiable since frozen=True
# If you need changing variables for modifying config - you must
# create an instance of like this: ConfigSample(frozen=False)
# But right now it will raise NotImplementedError
config.some_value = "random"

See examples with explanation here

Supported config formats

Yaml
Toml (read only with default lib included with python 3.11, and read-write with toml external lib)
Json (strings or files)
Environment variables
Pythons dictionaries
Composite loading from multiple simple loaders

Features

Loading configs from multiple sources
Creating custom loaders and variables types
Flexible configs definition
Config values validations
Casting variables values to specific types using functions
Casting to acceptable variable type before dumping variable to loader
Variables serialization/deserialization depending on from which loader it was fetched
Default values for per loader or per variable
Translating one config loaders data to other (with or without including default values for each one)
Composite loaders that allow you to define where to look up values using only one loader, that handles combining others
Simple access to variables values
Single entry point for initialization of config with loader

About 4.0

This version of ConfigFramework is not backwards compatible and requires a bit of work to make migration. It was needed to get rid of annoying initialization with one config loader per variable listing, which also made it really hard to replace config sources and made it more uncertain where is the source of data for variable.

What’s different?

Configs must get only one loader as input when initializing them, and all variables don’t have argument for specifying loader.
Added toml support for python above 3.11 and with external library that adds ability to read and write data.
Changes in internals regarding variables initialization to support assigning data from provided loader dynamically on initialization of whole config.
Added pyproject.toml for more modern package management.

Known issues

Typehint for Variable[any_type] doesn’t work properly and give only hints for Variable methods, while must give hints for any_type, when called from instance of any subclass of BaseConfig (This is related to Pycharm only and I can not fix it, see: https://youtrack.jetbrains.com/issue/PY-47698 )