Skip to content

Config

rn_forge.commons.config

Configuration loader with reference resolution.

Loads configuration from JSON or YAML files (single file or directory), deep-merges multiple files, and resolves internal references:

  • ${path} — value interpolation (replaces with the resolved value)
  • @{path} — dict reference (resolves to the dict at path)
  • #{path} — list reference (resolves to the list at path)
  • __extends__ key — inherits and merges from another dict path

Reference paths use the same dot-delimited notation as :meth:~rn_forge.commons.lang.collections.DictUtils.get.

Provides: Config: Immutable-ish configuration object loaded from one or more JSON/YAML files with automatic reference resolution.

Typical usage::

from rn_forge.commons.config import Config

cfg = Config("settings", "base.yaml")
db_host = cfg.get("database.host", default="localhost")

Config(*paths, config_type='yaml', resolve=True)

Immutable-ish configuration object with reference resolution.

Loads one or more JSON/YAML files, deep-merges them in sorted order, and optionally resolves internal ${}, @{}, #{} references and __extends__ inheritance.

Supports dict-like read access via cfg["key"], "key" in cfg, iter(cfg), and len(cfg).

Example::

from rn_forge.commons.config import Config

cfg = Config("config/")
host = cfg.get("database.host", default="localhost")
cfg.set("database.port", 5432)
raw = cfg.as_dict()

Reference forms::

service_url: "https://${service.host}:${service.port}"
database: "@{services.primary_db}"
all_hosts:
  - "#{services.hosts}"
  - "localhost"
production:
  __extends__: "@{profiles.base}"
  debug: false

Load and optionally resolve a configuration from file(s).

Parameters:

Name Type Description Default
*paths str | Path

Path segments joined via :class:~pathlib.Path. If the result is a file it is loaded directly; if a directory, all files matching *.{config_type} (recursively, sorted) are loaded and deep-merged.

()
config_type Literal['json', 'yaml']

"yaml" (default) or "json" — determines the file extension filter and parser.

'yaml'
resolve bool

When True (default), call :meth:resolve_references immediately after loading.

True

Raises:

Type Description
FileNotFoundError

If the resolved path does not exist.

__contains__(key)

Return True if key is a top-level key in the configuration.

Parameters:

Name Type Description Default
key object

The key to test.

required

Returns:

Type Description
bool

True if key exists at the top level, False otherwise.

__getitem__(key)

Return the top-level value for key (no dot-path support).

Parameters:

Name Type Description Default
key str

A top-level key in the configuration dict.

required

Returns:

Type Description
Any

The value at key.

Raises:

Type Description
KeyError

If key is not present.

__iter__()

Iterate over top-level keys in the configuration.

Returns:

Type Description
Iterator[str]

An iterator over top-level key strings.

__len__()

Return the number of top-level keys in the configuration.

Returns:

Type Description
int

An integer count of top-level keys.

__repr__()

Return an unambiguous string representation of this :class:Config.

Returns:

Type Description
str

A string of the form Config({...}).

as_dict()

Return a deep copy of the configuration data as a plain dict.

Returns:

Type Description
dict[str, Any]

A deep copy of the internal dict[str, Any]. Mutating the

dict[str, Any]

returned value does not affect this :class:Config instance.

get(key_path, *, default=None)

Retrieve a value using a dot-delimited key path.

Delegates to :meth:~rn_forge.commons.lang.collections.DictUtils.get.

Parameters:

Name Type Description Default
key_path str

Dot-delimited path, e.g. "database.host".

required
default Any

Value returned when the path cannot be resolved. Defaults to None.

None

Returns:

Type Description
Any

The resolved value, or default if the path is absent.

resolve_references()

Resolve all ${}, @{}, #{} references and __extends__ inheritance in the loaded configuration.

Called automatically when resolve=True (the default). Safe to call again after programmatic mutations.

Example::

cfg = Config("settings.yaml", resolve=False)
cfg.set("service.host", "localhost")
cfg.resolve_references()

set(key_path, value)

Set a value using a dot-delimited key path.

Delegates to :meth:~rn_forge.commons.lang.collections.DictUtils.set. Intermediate dicts are created automatically.

Parameters:

Name Type Description Default
key_path str

Dot-delimited path to the target key.

required
value Any

The value to assign.

required

Raises:

Type Description
KeyError

If a non-numeric index is used on a list segment.

IndexError

If a list index is out of bounds.

TypeError

If traversal encounters a non-container at an intermediate path segment.