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: Union[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: Union[DictConfig, ListConfig, Dict[Union[str, bytes, int, Enum, float, bool], Any], List[Any], Tuple[Any, ...], Any]) Union[ListConfig, DictConfig] [source]¶
Merge a list of previously created configs into a single one
- Parameters
configs – Input configs
- 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: Union[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) Union[Dict[Union[str, bytes, int, Enum, float, bool], Any], List[Any], None, str, Any] [source]¶
Resursively 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) Union[Dict[Union[str, bytes, int, Enum, float, bool], Any], List[Any], None, str, Any] [source]¶
Resursively 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: Union[DictConfig, ListConfig, Dict[Union[str, bytes, int, Enum, float, bool], Any], List[Any], Tuple[Any, ...], Any]) Union[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
- Returns
the merged config object.
- static update(cfg: Container, key: str, value: Optional[Any] = 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: Union[List[str], str], values: Optional[Union[List[Optional[bool]], bool]]) Generator[Node, None, None] ¶
- omegaconf.open_dict() Generator[Container, None, None] ¶
- omegaconf.read_write() Generator[Node, None, None] ¶
- omegaconf.MISSING¶
alias of ???