API Reference¶
The OmegaConf
API¶
- class omegaconf.OmegaConf[source]¶
OmegaConf primary class
- classmethod clear_resolver(name: str) bool [source]¶
Clear(remove) any resolver only if it exists.
Returns a bool: True if resolver is removed and False if not removed.
- Parameters:
name – Name of the resolver.
- Returns:
A bool (
True
if resolver is removed,False
if not found before removing).
- static clear_resolvers() None [source]¶
Clear(remove) all OmegaConf resolvers, then re-register OmegaConf’s default resolvers.
- static from_dotlist(dotlist: List[str]) DictConfig [source]¶
Creates config from the content sys.argv or from the specified args list of not None
- Parameters:
dotlist – A list of dotlist-style strings, e.g.
["foo.bar=1", "baz=qux"]
.- Returns:
A
DictConfig
object created from the dotlist.
- static masked_copy(conf: DictConfig, keys: str | List[str]) DictConfig [source]¶
Create a masked copy of of this config that contains a subset of the keys
- Parameters:
conf – DictConfig object
keys – keys to preserve in the copy
- Returns:
The masked
DictConfig
object.
- static merge(*configs: DictConfig | ListConfig | Dict[str | bytes | int | Enum | float | bool, Any] | List[Any] | Tuple[Any, ...] | Any, list_merge_mode: ListMergeMode = ListMergeMode.REPLACE) ListConfig | DictConfig [source]¶
Merge a list of previously created configs into a single one
- Parameters:
configs – Input configs
list_merge_mode – Behavior for merging lists REPLACE: Replaces the target list with the new one (default) EXTEND: Extends the target list with the new one EXTEND_UNIQUE: Extends the target list items with items not present in it hint: use from omegaconf import ListMergeMode to access the merge mode
- Returns:
the merged config object.
- static missing_keys(cfg: Any) Set[str] [source]¶
Returns a set of missing keys in a dotlist style.
- Parameters:
cfg – An
OmegaConf.Container
, or a convertible object viaOmegaConf.create
(dict, list, …).- Returns:
set of strings of the missing keys.
- Raises:
ValueError – On input not representing a config.
- static register_new_resolver(name: str, resolver: Callable[[...], Any], *, replace: bool = False, use_cache: bool = False) None [source]¶
Register a resolver.
- Parameters:
name – Name of the resolver.
resolver – Callable whose arguments are provided in the interpolation, e.g., with ${foo:x,0,${y.z}} these arguments are respectively “x” (str), 0 (int) and the value of
y.z
.replace – If set to
False
(default), then aValueError
is raised if an existing resolver has already been registered with the same name. If set toTrue
, then the new resolver replaces the previous one. NOTE: The cache on existing config objects is not affected, useOmegaConf.clear_cache(cfg)
to clear it.use_cache – Whether the resolver’s outputs should be cached. The cache is based only on the string literals representing the resolver arguments, e.g., ${foo:${bar}} will always return the same value regardless of the value of
bar
if the cache is enabled forfoo
.
- static resolve(cfg: Container) None [source]¶
Resolves all interpolations in the given config object in-place.
- Parameters:
cfg – An OmegaConf container (DictConfig, ListConfig) Raises a ValueError if the input object is not an OmegaConf container.
- static save(config: Any, f: str | Path | IO[Any], resolve: bool = False) None [source]¶
Save as configuration object to a file
- Parameters:
config – omegaconf.Config object (DictConfig or ListConfig).
f – filename or file object
resolve – True to save a resolved config (defaults to False)
- static select(cfg: Container, key: str, *, default: Any = _DEFAULT_MARKER_, throw_on_resolution_failure: bool = True, throw_on_missing: bool = False) Any [source]¶
- Parameters:
cfg – Config node to select from
key – Key to select
default – Default value to return if key is not found
throw_on_resolution_failure – Raise an exception if an interpolation resolution error occurs, otherwise return None
throw_on_missing – Raise an exception if an attempt to select a missing key (with the value ‘???’) is made, otherwise return None
- Returns:
selected value or None if not found.
- static to_container(cfg: Any, *, resolve: bool = False, throw_on_missing: bool = False, enum_to_str: bool = False, structured_config_mode: SCMode = SCMode.DICT) Dict[str | bytes | int | Enum | float | bool, Any] | List[Any] | None | str | Any [source]¶
Recursively converts an OmegaConf config to a primitive container (dict or list).
- Parameters:
cfg – the config to convert
resolve – True to resolve all values
throw_on_missing – When True, raise MissingMandatoryValue if any missing values are present. When False (the default), replace missing values with the string “???” in the output container.
enum_to_str – True to convert Enum keys and values to strings
structured_config_mode –
- Specify how Structured Configs (DictConfigs backed by a dataclass) are handled.
By default (
structured_config_mode=SCMode.DICT
) structured configs are converted to plain dicts.If
structured_config_mode=SCMode.DICT_CONFIG
, structured config nodes will remain as DictConfig.If
structured_config_mode=SCMode.INSTANTIATE
, this function will instantiate structured configs (DictConfigs backed by a dataclass), by creating an instance of the underlying dataclass.
See also OmegaConf.to_object.
- Returns:
A dict or a list representing this config as a primitive container.
- static to_object(cfg: Any) Dict[str | bytes | int | Enum | float | bool, Any] | List[Any] | None | str | Any [source]¶
Recursively converts an OmegaConf config to a primitive container (dict or list). Any DictConfig objects backed by dataclasses or attrs classes are instantiated as instances of those backing classes.
- This is an alias for OmegaConf.to_container(…, resolve=True, throw_on_missing=True,
structured_config_mode=SCMode.INSTANTIATE)
- Parameters:
cfg – the config to convert
- Returns:
A dict or a list or dataclass representing this config.
- static to_yaml(cfg: Any, *, resolve: bool = False, sort_keys: bool = False) str [source]¶
returns a yaml dump of this config object.
- Parameters:
cfg – Config object, Structured Config type or instance
resolve – if True, will return a string with the interpolations resolved, otherwise interpolations are preserved
sort_keys – If True, will print dict keys in sorted order. default False.
- Returns:
A string containing the yaml representation.
- static unsafe_merge(*configs: DictConfig | ListConfig | Dict[str | bytes | int | Enum | float | bool, Any] | List[Any] | Tuple[Any, ...] | Any, list_merge_mode: ListMergeMode = ListMergeMode.REPLACE) ListConfig | DictConfig [source]¶
Merge a list of previously created configs into a single one This is much faster than OmegaConf.merge() as the input configs are not copied. However, the input configs must not be used after this operation as will become inconsistent.
- Parameters:
configs – Input configs
list_merge_mode – Behavior for merging lists REPLACE: Replaces the target list with the new one (default) EXTEND: Extends the target list with the new one EXTEND_UNIQUE: Extends the target list items with items not present in it hint: use from omegaconf import ListMergeMode to access the merge mode
- Returns:
the merged config object.
- static update(cfg: Container, key: str, value: Any | None = None, *, merge: bool = True, force_add: bool = False) None [source]¶
Updates a dot separated key sequence to a value
- Parameters:
cfg – input config to update
key – key to update (can be a dot separated path)
value – value to set, if value if a list or a dict it will be merged or set depending on merge_config_values
merge – If value is a dict or a list, True (default) to merge into the destination, False to replace the destination.
force_add – insert the entire path regardless of Struct flag or Structured Config nodes.
Utility functions importable from the omegaconf
module¶
- omegaconf.II() Any ¶
Equivalent to
${interpolation}
- Parameters:
interpolation –
- Returns:
input
${node}
with type Any
- omegaconf.SI() Any ¶
Use this for String interpolation, for example
"http://${host}:${port}"
- Parameters:
interpolation – interpolation string
- Returns:
input interpolation with type
Any
- omegaconf.flag_override(names: List[str] | str, values: List[bool | None] | bool | None) Generator[Node, None, None] ¶
- omegaconf.open_dict() Generator[Container, None, None] ¶
- omegaconf.read_write() Generator[Node, None, None] ¶
- omegaconf.MISSING¶
alias of ???