API

dataclass_settings.load_settings(source_cls, *, loaders=(Env, Secret, Toml), extra_loaders=(), nested_delimiter=False, infer_names=False, emit_history=False)

Load settings from a supported source class.

Parameters:

  • source_cls (type[T]) – The root object to load settings for.

  • loaders (dataclass_settings.loader.LoaderTypes) – The set of loaders to use to load settings.

  • extra_loaders (dataclass_settings.loader.LoaderTypes) – Additional loaders to use. Distinct from loaders in that this option will not affect the set of default loaders.

  • nested_delimiter (bool | str) – Defaults to False. When True, “_” is used as the delimiter. When a string is provided, that is used as the delimiter.

  • infer_names (bool) – Defaults to False. When True, it informs loaders to infer the name of the setting from the name of the field ( akin to pydantic-settings’ default). When disabled, most loaders will require an explicit name.

  • emit_history (bool) – Defaults to False. When True, records the provenance of loaded secrets (evaluated names and values for each field) and log them in the event of a loading failure.

Return type:

T

Loaders

class dataclass_settings.loaders.Env(*env_vars)

Abstract base class for generic types.

A generic type is typically declared by inheriting from this class parameterized with one or more type variables. For example, a generic mapping type might be defined as:

class Mapping(Generic[KT, VT]):
    def __getitem__(self, key: KT) -> VT:
        ...
    # Etc.

This class can then be used as follows:

def lookup_name(mapping: Mapping[KT, VT], key: KT, default: VT) -> VT:
    try:
        return mapping[key]
    except KeyError:
        return default
Parameters:

env_vars (str)

env_vars: tuple[str, Ellipsis]
load(context, state)
Parameters:
Return type:

Any

classmethod load_with(*, env=None)
Parameters:

env (EnvLike | None)

Return type:

dataclass_settings.loader.DictState

class dataclass_settings.loaders.Secret(*names, dir=None)

Abstract base class for generic types.

A generic type is typically declared by inheriting from this class parameterized with one or more type variables. For example, a generic mapping type might be defined as:

class Mapping(Generic[KT, VT]):
    def __getitem__(self, key: KT) -> VT:
        ...
    # Etc.

This class can then be used as follows:

def lookup_name(mapping: Mapping[KT, VT], key: KT, default: VT) -> VT:
    try:
        return mapping[key]
    except KeyError:
        return default
Parameters:

  • names (str)

  • dir (Sequence[dataclass_settings.loader.PathLike] | None)

dir: Sequence[pathlib.PurePath] | None = None
load(context, state)
Parameters:
Return type:

Any

classmethod load_with(*, dir=None)
Parameters:

dir (Sequence[dataclass_settings.loader.PathLike] | None)

Return type:

SecretState

names: tuple[str, Ellipsis] = ()
with_dir(*dir)
Parameters:

dir (str)

Return type:

typing_extensions.Self

with_name(*names)
Parameters:

names (str)

Return type:

typing_extensions.Self

class dataclass_settings.loaders.Toml

Abstract base class for generic types.

A generic type is typically declared by inheriting from this class parameterized with one or more type variables. For example, a generic mapping type might be defined as:

class Mapping(Generic[KT, VT]):
    def __getitem__(self, key: KT) -> VT:
        ...
    # Etc.

This class can then be used as follows:

def lookup_name(mapping: Mapping[KT, VT], key: KT, default: VT) -> VT:
    try:
        return mapping[key]
    except KeyError:
        return default
file: str | pathlib.PurePath | None = None
key: str | None = None
load(context, state)
Parameters:
Return type:

Any

classmethod load_with(file=None)
Parameters:

file (str | pathlib.PurePath | None)

Return type:

TomlState

Context

class dataclass_settings.context.Context
enter(name)
Parameters:

name (str)

field_name: str | None = None
generate_load_history()
get_name(name)
Parameters:

name (str)

Return type:

str

get_state(loader)
Parameters:

loader (dataclass_settings.loader.Loader[dataclass_settings.loader.T])

Return type:

dataclass_settings.loader.T

infer_names: bool = False
property loaders: tuple[type[dataclass_settings.loader.Loader], Ellipsis]
Return type:

tuple[type[dataclass_settings.loader.Loader], Ellipsis]

property name
nested_delimiter: bool | str = False
path: list[str] = []
record_history: bool = False
record_loaded_value(loader, name, value)
Parameters:

  • loader (dataclass_settings.loader.Loader)

  • name (str)

  • value (Any)

resolve_loaders(*loaders_)
Parameters:

loaders_ (dataclass_settings.loader.LoaderTypes)

state: dict[type[dataclass_settings.loader.Loader], dataclass_settings.loader.LoaderState | None]