Reference

confarg ¶

A tool to manage complex configurations.

Load and resolve complex configurations from files, environment variables and command line arguments. Keep your data structures and favorite CLI library.

build ¶

build(target: type[T], data: dict[str, Any], *, union_tag: str = ...) -> T

build(target: object, data: dict[str, Any], *, union_tag: str = ...) -> Any

build(target, data, *, union_tag='class')

Resolve ${...} expressions and construct the target type from a merged config dict.

Use this as the second step after merge(), or to load configuration from a dict you have assembled yourself.

Parameters:

Name	Type	Description	Default
`target`	`type[T] \| TypeAliasType \| UnionType`	The dataclass type (or scalar type) to construct.	required
`data`	`dict[str, Any]`	The raw config dict (e.g. the output of `merge()`).	required
`union_tag`	`str`	The field name used as a discriminator tag in unions.	`'class'`

Returns:

Type	Description
`T`	An instance of the target type.

Raises:

Type	Description
`MissingFieldError`	If a required field is not provided.
`TypeCoercionError`	If a value cannot be coerced to the target type.
`AmbiguousUnionError`	If a Union cannot be disambiguated.
`CircularReferenceError`	If expression references form a cycle.
`UnsafeExpressionError`	If an expression contains disallowed constructs.
`MissingReferenceError`	If an expression references a field that does not exist.
`ExpressionEvalError`	If an expression fails at runtime.

dump ¶

dump(value, *, union_tag='class', tag_policy='auto')

Serialize a dataclass instance to a config-compatible plain dict.

Parameters:

Name	Type	Description	Default
`value`	`Any`	A dataclass instance.	required
`union_tag`	`str`	The field name used as a discriminator tag in unions.	`'class'`
`tag_policy`	`TagPolicy`	`"auto"` (tag only when needed) or `"always"` (tag every union member).	`'auto'`

Returns:

Type	Description
`dict[str, Any]`	A plain dict representation.

Raises:

Type	Description
`TypeError`	If value is not a dataclass instance.

dump_file ¶

dump_file(value, path, *, union_tag='class', tag_policy='auto')

Serialize and write to a config file.

Accepts a dataclass instance or a raw config dict (e.g. from merge() or resolve()). The output format is determined by the file extension (.toml, .yaml, .yml, .json).

Parameters:

Name	Type	Description	Default
`value`	`Any`	A dataclass instance or a raw config dict.	required
`path`	`str \| Path`	Path to the output file.	required
`union_tag`	`str`	The field name used as a discriminator tag in unions.	`'class'`
`tag_policy`	`TagPolicy`	`"auto"` or `"always"`.	`'auto'`

Raises:

Type	Description
`TypeError`	If value is not a dataclass instance or a dict.
`InvalidConfigFileError`	If the format is unsupported or the required library is not installed.

from_dict ¶

from_dict(target: type[T], data: dict[str, Any], *, union_tag: str = ...) -> T

from_dict(target: object, data: dict[str, Any], *, union_tag: str = ...) -> Any

from_dict(target, data, *, union_tag='class')

Construct a typed object from an already-resolved config dict.

Unlike build(), this does NOT resolve ${...} expressions — call resolve() first if needed.

Parameters:

Name	Type	Description	Default
`target`	`type[T] \| TypeAliasType \| UnionType`	The dataclass or plain-class type to construct.	required
`data`	`dict[str, Any]`	A resolved config dict (output of resolve() or merge()).	required
`union_tag`	`str`	The field name used as a discriminator tag in unions.	`'class'`

Returns:

Type	Description
`T`	An instance of the target type.

Raises:

Type	Description
`MissingFieldError`	If a required field is not provided.
`TypeCoercionError`	If a value cannot be coerced to the target type.
`AmbiguousUnionError`	If a Union cannot be disambiguated.

load ¶

load(target: type[T], *, argv: Sequence[str] | None = ..., env: Mapping[str, str] | None = ..., env_prefix: str | None = ..., env_separator: str = ..., cli_prefix: str = ..., config_flag: str = ..., files: Sequence[str | Path] = ..., env_config: str | None = ..., union_tag: str = ...) -> T

load(target: object, *, argv: Sequence[str] | None = ..., env: Mapping[str, str] | None = ..., env_prefix: str | None = ..., env_separator: str = ..., cli_prefix: str = ..., config_flag: str = ..., files: Sequence[str | Path] = ..., env_config: str | None = ..., union_tag: str = ...) -> Any

load(target, *, argv=None, env=None, env_prefix=_defaults.ENV_PREFIX, env_separator='__', cli_prefix='', config_flag='config', files=(), env_config=None, union_tag=_defaults.UNION_TAG)

Merge configuration from all sources and construct the target type.

Convenience wrapper for merge() + build(). For more control — e.g. to inspect or save the raw merged dict — call those directly. See merge() for source priority and config file loading order.

Parameters:

Name	Type	Description	Default
`target`	`type[T] \| TypeAliasType \| UnionType`	The dataclass type (or scalar type) to load configuration into.	required
`argv`	`Sequence[str] \| None`	CLI arguments to parse. Defaults to sys.argv[1:].	`None`
`env`	`Mapping[str, str] \| None`	Environment variable mapping to scan. Defaults to os.environ.	`None`
`env_prefix`	`str \| None`	Prefix that env vars must start with. Defaults to `None`, which disables environment variable parsing entirely. Set to `""` to read all env vars without filtering, or to e.g. `"MYAPP_"` to read only vars with that prefix.	`ENV_PREFIX`
`env_separator`	`str`	Separator used to split env var names into nested keys. Defaults to `"__"` (double underscore).	`'__'`
`cli_prefix`	`str`	Required prefix for all CLI flags. Defaults to `""`, which means no prefix is required.	`''`
`config_flag`	`str`	Flag name used to specify config files on the CLI (`--config path/to/file.yaml`). Set to `""` to disable. Defaults to `"config"`.	`'config'`
`files`	`Sequence[str \| Path]`	Paths to config files to load.	`()`
`env_config`	`str \| None`	Name of an env var whose value is a config file path to load. Loaded after `files` but before CLI `--config` files.	`None`
`union_tag`	`str`	Field name used as a discriminator tag in union types. Defaults to `"class"` — a Python keyword that can never clash with a dataclass field name.	`UNION_TAG`

Returns:

Type	Description
`T`	An instance of the target type populated with the merged configuration.

Raises:

Type	Description
`MissingFieldError`	If a required field is not provided by any source.
`TypeCoercionError`	If a value cannot be coerced to the target type.
`InvalidConfigFileError`	If a config file cannot be loaded.
`UnknownArgumentError`	If an unrecognized CLI argument is encountered.
`AmbiguousUnionError`	If a Union cannot be disambiguated.
`CircularReferenceError`	If expression references form a cycle.
`UnsafeExpressionError`	If an expression contains disallowed constructs.
`MissingReferenceError`	If an expression references a field that does not exist.
`ExpressionEvalError`	If an expression fails at runtime.

merge ¶

merge(target, *, argv=None, env=None, env_prefix=_defaults.ENV_PREFIX, env_separator='__', cli_prefix='', config_flag='config', files=(), env_config=None, union_tag=_defaults.UNION_TAG)

Collect and merge configuration from all sources into a raw dict.

Sources are merged in priority order: config files (lowest), then environment variables, then CLI arguments (highest). No expression resolution and no dataclass construction are performed — the returned dict reflects the config input exactly as written, with ${...} expression strings preserved.

Parameters:

Name	Type	Description	Default
`target`	`type \| TypeAliasType \| UnionType`	The dataclass type (or scalar type) used to guide CLI parsing.	required
`argv`	`Sequence[str] \| None`	CLI arguments to parse. Defaults to sys.argv[1:].	`None`
`env`	`Mapping[str, str] \| None`	Environment variable mapping to scan. Defaults to os.environ.	`None`
`env_prefix`	`str \| None`	Prefix that env vars must start with. Defaults to `None`, which disables environment variable parsing entirely. Set to `""` to read all env vars without filtering, or to e.g. `"MYAPP_"` to read only vars with that prefix.	`ENV_PREFIX`
`env_separator`	`str`	Separator used to split env var names into nested keys. Defaults to `"__"` (double underscore).	`'__'`
`cli_prefix`	`str`	Required prefix for all CLI flags. Defaults to `""`, which means no prefix is required.	`''`
`config_flag`	`str`	Flag name used to specify config files on the CLI (`--config path/to/file.yaml`). Set to `""` to disable. Defaults to `"config"`.	`'config'`
`files`	`Sequence[str \| Path]`	Paths to config files to load.	`()`
`env_config`	`str \| None`	Name of an env var whose value is a config file path to load. Loaded after `files` but before CLI `--config` files.	`None`
`union_tag`	`str`	Field name used as a discriminator tag in union types. Defaults to `"class"` — a Python keyword that can never clash with a dataclass field name.	`UNION_TAG`

Returns:

Type	Description
`dict[str, Any]`	A plain dict of the merged configuration, with expression strings intact.

Config file loading order

All config files share the same priority level (below inline env vars and CLI args). Within that level they are loaded left-to-right so that later sources win on conflict. The full sequence is:

files — in the order given.
env_config — the single global path named by that env var (if set).
CONFIG__* env vars — sorted lexicographically by their env var name, which is equivalent to sorting by subpath depth (shallower paths first). A global CONFIG=file therefore loads before CONFIG__DB=db.yaml, which loads before CONFIG__DB__HOST=host.yaml.
CLI --config / --config.subpath flags — in left-to-right order.

Raises:

Type	Description
`InvalidConfigFileError`	If a config file cannot be loaded.
`UnknownArgumentError`	If an unrecognized CLI argument is encountered.

resolve ¶

resolve(data)

Resolve ${...} expressions in a merged config dict.

Use this between merge() and from_dict() when you need the resolved dict itself (e.g. to inspect values or write it to a file):

raw = confarg.merge(MyConfig, ...)
resolved = confarg.resolve(raw)
confarg.dump_file(resolved, "out.yaml")
cfg = confarg.from_dict(MyConfig, resolved)

Parameters:

Name	Type	Description	Default
`data`	`dict[str, Any]`	A plain config dict, e.g. the output of `merge()`.	required

Returns:

Type	Description
`dict[str, Any]`	A new dict with all `${...}` expression strings replaced by their values.

Raises:

Type	Description
`CircularReferenceError`	If expression references form a cycle.
`UnsafeExpressionError`	If an expression contains disallowed constructs.
`MissingReferenceError`	If an expression references a field that does not exist.
`ExpressionEvalError`	If an expression fails at runtime.