loaders

Loaders retrieve data from sources such as files and environment variables and create a tree to be used by load_config.

A loader is just a function that takes parameter and return a dictionary. A loader factory is a wrapper over a loader which accepts only one parameter: a configclass used for the result validation.

load_config normally treats all callables as function loader of this kind and pass them the configclass of the configuration we are loading.

subpath

In some situations you might want to validate only a subset of a configuration, in these cases the subpath argument of the loader may be handy.

@configclass
class ServerConfig:
    host: str
    port: int

@configclass
class ApplicationConfig:
    name: str = "spam"
    server: ServerConfig

config = load_config(
    ApplicationConfig,
    file_loader(cls=ServerConfig, subpath="server", files=["~/.spam.json"])
)

The result loaded by file path will be first validated against the cls schema and then wrapped in a tree at the given subpath.

Note

We are passing the cls parameter, otherwise the validation would be performed against the ApplicationConfig schema before the wrapping. Not what we want!

env_loader(*, cls=None, subpath=None, mapping, validate=False, prefix='', env=None)

Create a new loader for environment variables.

Accept the same parameters of load_env but return a callable instead.

Parameters:

Name	Type	Description	Default
cls	type[_T] | None	class to use for validation.	None
mapping	Mapping[str, str]	the variable mapping.	required
subpath	str | Sequence[str] | None	wrap the result in the subpath of a new dict.	None
validate	bool	validate the result against the cls.	False
prefix	str	prefix to apply to all keys in the mapping.	''
env	Mapping[str, str] | None	dict to use instead of the environment variables. If None use os.environ.	None

Returns:

Type	Description
Callable[[type], dict[str, Any]]	A function that can be used as a source for the configuration. See load_config.

file_loader(*, cls=None, subpath=None, files, supported_file_types=None, validate=True, load_all_files=False, load_at_least_one_file=False)

Return a new loader to be used by load_config.

This is just a wrapper for load_file.

Parameters:

Name	Type	Description	Default
cls	type | None	class used for validation.	None
files	Iterable[str | Path] | str | Path	either a file path or a list of file paths.	required
subpath	str | Sequence[str] | None	wrap the result in the subpath of a new dict. Validation is done before wrapping.	None
supported_file_types	Sequence[FileType] | None	list of supported file types. None means all of them.	None
validate	bool	validate the result.	True
load_all_files	bool	if False unexisting files are skipped.	False
load_at_least_one_file	bool	if True an exception is raised when no files are loaded.	False

Returns:

Type	Description
Callable[[type], list[dict[str, Any]]]	A function that can be used as a source for the configuration. See load_config.

load_env(cls=None, *, mapping, subpath=None, validate=False, prefix='', env=None)

Load a dict from environment variables.

Given a mapping envvar -> dotted.path, creates a dict where each dotted.path contains the variable of the envvar.

Missing variables are ignored.

Examples:

>>> load_env(
...   mapping={"VAR1": "a.b", "VAR2": "a.c", "MISS": "b.c"},
...   env={"VAR1": "var1", "VAR2": "var2"}
... )
{'a': {'b': 'var1', 'c': 'var2'}}

Parameters:

Name	Type	Description	Default
cls	type[_T] | None	class to use for validation.	None
mapping	Mapping[str, str]	the variable mapping.	required
subpath	str | Sequence[str] | None	wrap the result in the subpath of a new dict.	None
validate	bool	validate the result against the cls.	False
prefix	str	prefix to apply to all keys in the mapping.	''
env	Mapping[str, str] | None	dict to use instead of the environment variables. If None use os.environ.	None

Returns:

Type	Description
dict[str, Any]	A dict that can be used as a source for the configuration. See load_config.

load_file(cls, *, files, subpath=None, supported_file_types=None, validate=True, load_all_files=False, load_at_least_one_file=False)

Load a config file or multiple config files.

Parameters:

Name	Type	Description	Default
cls	type[_T]	class used for validation.	required
files	Iterable[str | Path] | str | Path	either a file path or a list of file paths.	required
subpath	str | Sequence[str] | None	wrap the result in the subpath of a new dict. Validation is done before wrapping.	None
supported_file_types	Sequence[FileType] | None	list of supported file types. None means all of them.	None
validate	bool	validate the result.	True
load_all_files	bool	if False unexisting files are skipped.	False
load_at_least_one_file	bool	if True an exception is raised when no files are loaded.	False

Returns:

Type	Description
list[dict[str, Any]]	A list of dictionary to be used as a source for
list[dict[str, Any]]	load_config.

env

Environment variable loaders.

env_loader(*, cls=None, subpath=None, mapping, validate=False, prefix='', env=None)

Create a new loader for environment variables.

Accept the same parameters of load_env but return a callable instead.

Parameters:

Name	Type	Description	Default
cls	type[_T] | None	class to use for validation.	None
mapping	Mapping[str, str]	the variable mapping.	required
subpath	str | Sequence[str] | None	wrap the result in the subpath of a new dict.	None
validate	bool	validate the result against the cls.	False
prefix	str	prefix to apply to all keys in the mapping.	''
env	Mapping[str, str] | None	dict to use instead of the environment variables. If None use os.environ.	None

Returns:

Type	Description
Callable[[type], dict[str, Any]]	A function that can be used as a source for the configuration. See load_config.

load_env(cls=None, *, mapping, subpath=None, validate=False, prefix='', env=None)

Load a dict from environment variables.

Given a mapping envvar -> dotted.path, creates a dict where each dotted.path contains the variable of the envvar.

Missing variables are ignored.

Examples:

>>> load_env(
...   mapping={"VAR1": "a.b", "VAR2": "a.c", "MISS": "b.c"},
...   env={"VAR1": "var1", "VAR2": "var2"}
... )
{'a': {'b': 'var1', 'c': 'var2'}}

Parameters:

Name	Type	Description	Default
cls	type[_T] | None	class to use for validation.	None
mapping	Mapping[str, str]	the variable mapping.	required
subpath	str | Sequence[str] | None	wrap the result in the subpath of a new dict.	None
validate	bool	validate the result against the cls.	False
prefix	str	prefix to apply to all keys in the mapping.	''
env	Mapping[str, str] | None	dict to use instead of the environment variables. If None use os.environ.	None

Returns:

Type	Description
dict[str, Any]	A dict that can be used as a source for the configuration. See load_config.

file

File loaders.

Support multiple file formats and multiple files. (e.g. default config + user overrides)

file_loader(*, cls=None, subpath=None, files, supported_file_types=None, validate=True, load_all_files=False, load_at_least_one_file=False)

Return a new loader to be used by load_config.

This is just a wrapper for load_file.

Parameters:

Name	Type	Description	Default
cls	type | None	class used for validation.	None
files	Iterable[str | Path] | str | Path	either a file path or a list of file paths.	required
subpath	str | Sequence[str] | None	wrap the result in the subpath of a new dict. Validation is done before wrapping.	None
supported_file_types	Sequence[FileType] | None	list of supported file types. None means all of them.	None
validate	bool	validate the result.	True
load_all_files	bool	if False unexisting files are skipped.	False
load_at_least_one_file	bool	if True an exception is raised when no files are loaded.	False

Returns:

Type	Description
Callable[[type], list[dict[str, Any]]]	A function that can be used as a source for the configuration. See load_config.

load_file(cls, *, files, subpath=None, supported_file_types=None, validate=True, load_all_files=False, load_at_least_one_file=False)

Load a config file or multiple config files.

Parameters:

Name	Type	Description	Default
cls	type[_T]	class used for validation.	required
files	Iterable[str | Path] | str | Path	either a file path or a list of file paths.	required
subpath	str | Sequence[str] | None	wrap the result in the subpath of a new dict. Validation is done before wrapping.	None
supported_file_types	Sequence[FileType] | None	list of supported file types. None means all of them.	None
validate	bool	validate the result.	True
load_all_files	bool	if False unexisting files are skipped.	False
load_at_least_one_file	bool	if True an exception is raised when no files are loaded.	False

Returns:

Type	Description
list[dict[str, Any]]	A list of dictionary to be used as a source for
list[dict[str, Any]]	load_config.