Reference

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:

Returns:

Raises:

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

The dump records the values the instance holds, not how they were produced: ${...} expressions are written as their resolved values, and a value a call: spec computed is written as that value, not as the call. To save a configuration as written, with its expressions and its call: specs, pass the dict returned by merge() to dump_file() instead. Plain (non-dataclass) classes are not supported.

Parameters:

Returns:

Raises:

Serialize and write to a config file.

Accepts a dataclass instance or a raw config dict (e.g. from merge() or resolve()). A dict is written as it stands, so the dict merge() returns keeps its ${...} expressions and call: specs; an instance is written as dump() serializes it, as the values it holds. The output format is determined by the file extension (.toml, .yaml, .yml, .json).

Parameters:

Raises:

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

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

Parameters:

Returns:

Raises:

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:

Returns:

Raises:

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.

The returned dict is unvalidated: it is not guaranteed to be constructible into target. Type validation and coercion happen in build() (or the one-shot load()), which raises TypeCoercionError / MissingFieldError for data that cannot be built. CLI parsing rejects only the cases it can prove wrong at parse time (e.g. a missing value); a config file or env var carrying "abc" for an int field merges cleanly here and fails later, in build().

Parameters:

Returns:

Raises:

Register a custom leaf type.

After registration, tp is treated as a leaf in both directions: values of that type can appear as scalars in config files, env vars, and CLI args, and they are written back as scalars by dump() and dump_file(), even if tp would otherwise be constructed field by field as a class.

coerce is called with the raw input value — either a str subclass from CLI, env and CSV sources, or the natively-parsed Python object from config files — and must return an instance of tp, raising ValueError, TypeError or OSError on failure. Values that already are instances of tp are used as-is. Unresolved ${...} expressions are never passed to coerce; it receives their resolved value.

serialize is the inverse: it is called with an instance of tp and must return a value a config file can hold (a string, number or bool), which coerce accepts back. It defaults to str, which is right for types whose str() is their wire form (UUID, Decimal, Path) and wrong for types whose __str__ is a repr-style debugging aid — pass an explicit callable for those, or dumps will not load back.

Example::

from uuid import UUID
confarg.register_leaf_type(UUID, UUID)            # str() is the wire form

confarg.register_leaf_type(Int, coerce_int, serialize=lambda i: i.value)

Register a handler that reads config sources for a URL scheme.

After registration, any location beginning <scheme>: can be used wherever a configuration file path can: files=, env_config, <PREFIX>CONFIG__<SUBPATH>, --config[.subpath][+] and __include__.

read is called with the full location string exactly as it was written -- "gs://bucket/path/config.yaml" -- and must return the document's raw bytes. confarg decodes them itself, so a handler never chooses an encoding: that keeps a BOM working in JSON and CSV, which a decoded str would break. Raise OSError (or confarg.exceptions.InvalidConfigFileError) when the document cannot be read; anything else propagates unchanged.

The format is still chosen by the extension of the location's path, so a handler is not asked about it and a location with no extension is rejected. Relative __include__ paths inside a document fetched this way resolve against its own location and may not leave its scheme and host.

file, http, https and s3 are registered already (s3 needs boto3: pip install confarg[s3]). Registering one of those names again replaces it, which is how an application adds authentication, a different timeout, or caching.

Example::

import urllib.request

def read_authenticated(location: str) -> bytes:
    request = urllib.request.Request(location, headers={"Authorization": TOKEN})
    with urllib.request.urlopen(request, timeout=30) as response:
        return response.read()

confarg.register_scheme("https", read_authenticated)   # replace the built-in
confarg.register_scheme("gs", read_gcs)                # or add a new scheme

Resolve ${...} expressions in a merged config dict, over the target's field defaults.

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(MyConfig, raw)
confarg.dump_file(resolved, "out.yaml")
cfg = confarg.from_dict(MyConfig, resolved)

The target's field defaults are the layer below data: an expression reads a default nobody set, and a patch the merge left pending over a defaulted field (--t+ 3) is applied over the default. A default nothing touched is not in the result; construction applies it.

Parameters:

Returns:

Raises:

Remove the reader registered for a URL scheme, a built-in one included.

A location naming the scheme afterwards is refused the way any unknown scheme is, with InvalidConfigFileError naming the schemes that remain -- from every channel, since the registry is global. unregister_scheme("http") and unregister_scheme("https") are therefore how an application forbids loading configuration over the network at all::

confarg.unregister_scheme("http")
confarg.unregister_scheme("https")
confarg.load(Config, files=["https://cfg.example.com/app.yaml"])  # raises

The scheme name is matched case-insensitively and may be written with its separator ("HTTP", "http:" and "http://" all name the same entry).

Removing a scheme is not how a handler is replaced -- pass the new reader to :func:register_scheme instead, which overwrites in place.

Raises: