coma.config.base

Base of config utilities implementation.

class InstanceKeys

Collection of standard instance keys used for Config in core coma. User-defined keys beyond these can exist.

BASE

The base instance that results from direct initialization.

Type:

str

FILE

The instance that results from loading a config from file.

Type:

str

OVERRIDE

The instance that results from overriding another instance with command-line arguments.

Type:

str

InstanceKey

Type alias for instance keys.

Identifier

Type alias for a valid Python identifier.

ConfigID

Type alias for config identifiers. Must be a valid Python identifier.

Configs

Type alias for mapping between config identifiers and Config s.

ParamID

Type alias for parameter identifiers. Must be a valid Python identifier.

Parameters

Type alias for a mapping between parameter identifiers and values.

class Config(back_end: ~typing.Any, instances: dict[str, ~typing.Any] = <factory>)

Wrapper for config data. Manages all viable instances of a config. Typically, a new instance variant is created whenever major changes to the config data are made.

back_end

The backing construct of the config. Must be an omegaconf-supported type, which means either a list object, a dict object, or a dataclass type or object.

Type:

Any

instances

The collection of instance variants of back_end mapped by variant keys.

Type:

dict[InstanceKey, typing.Any]

has(key: str) → bool

Returns whether this Config has an instance corresponding to key.

get(key: str) → Any

Returns the instance corresponding to key.

Parameters:

key (InstanceKey) – The instance key.

Returns:

The corresponding instance.

Return type:

Any

Raises:

KeyError – If no corresponding instance exists.

set(key: str, instance: Any, force_latest: bool = False) → None

Sets or updates the instance corresponding to key.

Parameters:

• key (InstanceKey) – The instance variant key for which to set or update the instance data.

• instance (Any) – The instance data to set for key.

• force_latest (bool) – Whether to force key to be interpreted as the latest (at least until the next call to set()).

See also

• get_latest()

• get_latest_key()

delete(key: str, raise_on_missing: bool = False) → None

Deletes the instance corresponding to key.

Parameters:

• key (InstanceKey) – The instance variant key for which to delete the instance data.

• raise_on_missing (bool) – Whether to raise an error when no instance variant corresponding to key exists or no nothing silently.

Raises:

KeyError – If no instance corresponding to key exists and raise_on_missing is True.

get_latest() → Any

Returns the latest instance.

Note

This is the latest by insertion order. Newer overwrites of existing instances don’t count as latest unless force_latest is True on calls to set().

Raises:

ValueError – If there are no instances at all and so no latest instance.

See also

• get_latest_key()

get_latest_key() → str

Returns the key of the latest instance.

Note

This is the latest by insertion order. Newer overwrites of existing instances don’t count as latest unless force_latest is True on calls to set().

Returns:

The key corresponding to the latest instance to be set.

Return type:

InstanceKey

Raises:

ValueError – If there are no instances at all and so no latest instance.

See also

• get_latest()

get_or_latest(key: str | None = None) → Any

Returns the instance corresponding to key unless key is None in which case the latest instance is returned instead.

Returns:

The corresponding instance.

Return type:

Any

Raises:

• KeyError – If key is not None, but no corresponding instance exists.

• ValueError – If key is None, but there are no instances at all and so no latest instance.

See also

• get_latest()

make_latest(key: str) → None

Forces the given key to be interpreted as the latest (at least until a new key gets added).

Raises:

KeyError – If no corresponding instance exists.

See also

• get_latest()

is_primitive(key: str) → bool

Returns whether the instance data corresponding to key is a primitive Python object (list, dict, or dataclass) as opposed to an omegaconf container object.

Raises:

KeyError – If no corresponding instance exists.

as_primitive(key: str, *, resolve: bool = True, throw_on_missing: bool = True, enum_to_str: bool = False, structured_config_mode: SCMode = SCMode.INSTANTIATE) → Any

Returns the instance data corresponding to key as a primitive Python object (list, dict, or dataclass) instead of an omegaconf container object.

If the instance is already primitive, returns it directly.

Does not update the underlying instance. To do so, use set().

Parameters:

• key (InstanceKey) – The instance variant key for which to convert the instance data into a primitive.

• resolve (bool) – Passed to OmegaConf.to_container().

• throw_on_missing (bool) – Passed to OmegaConf.to_container().

• enum_to_str (bool) – Passed to OmegaConf.to_container().

• structured_config_mode (omegaconf.base.SCMode) – Passed to OmegaConf.to_container().

Returns:

The instance data for key as a Python primitive.

Return type:

Any

Raises:

• KeyError – If no corresponding instance exists.

• Others – As may be raised by OmegaConf.to_container().

from_primitive(key: str, *, parent: BaseContainer | None = None, flags: dict[str, bool] | None = None) → Any

Returns the instance data corresponding to key as an omegaconf container object instead of a primitive Python object (list, dict, or dataclass).

If the instance is already an omegaconf container, returns it directly.

Does not update the underlying instance. To do so, use set().

Parameters:

• key (InstanceKey) – The instance variant key for which to convert the instance data into a primitive.

• parent (omegaconf.basecontainer.BaseContainer, optional) – Passed to OmegaConf.create().

• flags (dict[str, bool], optional) – Passed to OmegaConf.create().

Returns:

The instance data for key as an omegaconf container.

Return type:

Any

Raises:

• KeyError – If no corresponding instance exists.

• Others – As may be raised by OmegaConf.create().