Creating¶
You can create OmegaConf objects from multiple sources.
Empty¶
>>> from omegaconf import OmegaConf
>>> conf = OmegaConf.create()
>>> print(OmegaConf.to_yaml(conf))
{}
From a dictionary¶
>>> conf = OmegaConf.create({"k" : "v", "list" : [1, {"a": "1", "b": "2", 3: "c"}]})
>>> print(OmegaConf.to_yaml(conf))
k: v
list:
- 1
- a: '1'
b: '2'
3: c
Here is an example of various supported key types:
>>> from enum import Enum
>>> class Color(Enum):
... RED = 1
... BLUE = 2
>>>
>>> conf = OmegaConf.create(
... {"key": "str", 123: "int", True: "bool", 3.14: "float", Color.RED: "Color"}
... )
>>>
>>> print(conf)
{'key': 'str', 123: 'int', True: 'bool', 3.14: 'float', <Color.RED: 1>: 'Color'}
OmegaConf supports str
, int
, bool
, float
and Enums as dictionary key types.
From a list¶
>>> conf = OmegaConf.create([1, {"a":10, "b": {"a":10, 123: "int_key"}}])
>>> print(OmegaConf.to_yaml(conf))
- 1
- a: 10
b:
a: 10
123: int_key
Tuples are supported as a valid option too.
From a YAML file¶
>>> conf = OmegaConf.load('source/example.yaml')
>>> # Output is identical to the YAML file
>>> print(OmegaConf.to_yaml(conf))
server:
port: 80
log:
file: ???
rotation: 3600
users:
- user1
- user2
From a YAML string¶
>>> s = """
... a: b
... b: c
... list:
... - item1
... - item2
... 123: 456
... """
>>> conf = OmegaConf.create(s)
>>> print(OmegaConf.to_yaml(conf))
a: b
b: c
list:
- item1
- item2
123: 456
From a dot-list¶
>>> dot_list = ["a.aa.aaa=1", "a.aa.bbb=2", "a.bb.aaa=3", "a.bb.bbb=4"]
>>> conf = OmegaConf.from_dotlist(dot_list)
>>> print(OmegaConf.to_yaml(conf))
a:
aa:
aaa: 1
bbb: 2
bb:
aaa: 3
bbb: 4
From command line arguments¶
To parse the content of sys.arg:
>>> # Simulating command line arguments
>>> sys.argv = ['your-program.py', 'server.port=82', 'log.file=log2.txt']
>>> conf = OmegaConf.from_cli()
>>> print(OmegaConf.to_yaml(conf))
server:
port: 82
log:
file: log2.txt
From structured config¶
You can create OmegaConf objects from structured config classes or objects. This provides static and runtime type safety. See Structured config for more details, or keep reading for a minimal example.
>>> from dataclasses import dataclass
>>> @dataclass
... class MyConfig:
... port: int = 80
... host: str = "localhost"
>>> # For strict typing purposes, prefer OmegaConf.structured() when creating structured configs
>>> conf = OmegaConf.structured(MyConfig)
>>> print(OmegaConf.to_yaml(conf))
port: 80
host: localhost
You can use an object to initialize the config as well:
>>> conf = OmegaConf.structured(MyConfig(port=443))
>>> print(OmegaConf.to_yaml(conf))
port: 443
host: localhost
OmegaConf objects constructed from Structured classes provide runtime type safety:
>>> conf.port = 42 # Ok, type matches
>>> conf.port = "1080" # Ok! "1080" can be converted to an int
>>> conf.port = "oops" # "oops" cannot be converted to an int
Traceback (most recent call last):
...
omegaconf.errors.ValidationError: Value 'oops' could not be converted to Integer
In addition, the config class can be used as type annotation for static type checkers or IDEs:
>>> def foo(conf: MyConfig):
... print(conf.port) # passes static type checker
... print(conf.pork) # fails static type checker
Access and manipulation¶
Input YAML file for this section:
server:
port: 80
log:
file: ???
rotation: 3600
users:
- user1
- user2
Access¶
>>> # object style access of dictionary elements
>>> conf.server.port
80
>>> # dictionary style access
>>> conf['log']['rotation']
3600
>>> # items in list
>>> conf.users[0]
'user1'
Default values¶
You can provide default values directly in the accessing code:
>>> conf.get('missing_key', 'a default value')
'a default value'
Mandatory values¶
Use the value "???"
to indicate parameters that need to be set prior to access
>>> conf.log.file
Traceback (most recent call last):
...
omegaconf.MissingMandatoryValue: log.file
Manipulation¶
>>> # Changing existing keys
>>> conf.server.port = 81
>>> # Adding new keys
>>> conf.server.hostname = "localhost"
>>> # Adding a new dictionary
>>> conf.database = {'hostname': 'database01', 'port': 3306}
Serialization¶
OmegaConf objects can be saved and loaded with OmegaConf.save() and OmegaConf.load(). The created file is in YAML format. Save and load can operate on file-names, Paths and file objects.
Save/Load YAML file¶
>>> conf = OmegaConf.create({"foo": 10, "bar": 20, 123: 456})
>>> with tempfile.NamedTemporaryFile() as fp:
... OmegaConf.save(config=conf, f=fp.name)
... loaded = OmegaConf.load(fp.name)
... assert conf == loaded
Note that this does not retain type information.
Save/Load pickle file¶
Use pickle to save and load while retaining the type information. Note that the saved file may be incompatible across different versions of OmegaConf.
>>> conf = OmegaConf.create({"foo": 10, "bar": 20, 123: 456})
>>> with tempfile.TemporaryFile() as fp:
... pickle.dump(conf, fp)
... fp.flush()
... assert fp.seek(0) == 0
... loaded = pickle.load(fp)
... assert conf == loaded
Variable interpolation¶
OmegaConf supports variable interpolation. Interpolations are evaluated lazily on access.
Config node interpolation¶
The interpolated variable can be the path to another node in the configuration, and in that case
the value will be the value of that node.
This path may use either dot-notation (foo.1
), brackets ([foo][1]
) or a mix of both (foo[1]
, [foo].1
).
Interpolations are absolute by default. Relative interpolation are prefixed by one or more dots:
The first dot denotes the level of the node itself and additional dots are going up the parent hierarchy.
e.g. ${..foo}
points to the foo
sibling of the parent of the current node.
NOTE: Interpolations may cause config cycles. Such cycles are forbidden and may cause undefined behavior.
Input YAML file:
server:
host: localhost
port: 80
client:
url: http://${server.host}:${server.port}/
server_port: ${server.port}
# relative interpolation
description: Client of ${.url}
Example:
>>> conf = OmegaConf.load('source/config_interpolation.yaml')
>>> def show(x):
... print(f"type: {type(x).__name__}, value: {repr(x)}")
>>> # Primitive interpolation types are inherited from the reference
>>> show(conf.client.server_port)
type: int, value: 80
>>> # String interpolations concatenate fragments into a string
>>> show(conf.client.url)
type: str, value: 'http://localhost:80/'
>>> # Relative interpolation example
>>> show(conf.client.description)
type: str, value: 'Client of http://localhost:80/'
Interpolations may be nested, enabling more advanced behavior like dynamically selecting a sub-config:
>>> cfg = OmegaConf.create(
... {
... "plans": {
... "A": "plan A",
... "B": "plan B",
... },
... "selected_plan": "A",
... "plan": "${plans[${selected_plan}]}",
... }
... )
>>> cfg.plan # default plan
'plan A'
>>> cfg.selected_plan = "B"
>>> cfg.plan # new plan
'plan B'
Interpolated nodes can be any node in the config, not just leaf nodes:
>>> cfg = OmegaConf.create(
... {
... "john": {"height": 180, "weight": 75},
... "player": "${john}",
... }
... )
>>> (cfg.player.height, cfg.player.weight)
(180, 75)
Resolvers¶
Add new interpolation types by registering resolvers using OmegaConf.register_new_resolver()
.
Such resolvers are called when the config node is accessed.
The minimal example below shows its most basic usage, see Custom resolvers for more details.
>>> OmegaConf.register_new_resolver(
... "add", lambda *numbers: sum(numbers)
... )
>>> c = OmegaConf.create({'total': '${add:1,2,3}'})
>>> c.total
6
Built-in resolvers¶
OmegaConf comes with a set of built-in custom resolvers:
- oc.create: Dynamically generating config nodes
- oc.decode: Parsing an input string using interpolation grammar
- oc.deprecated: Deprecate a key in your config
- oc.env: Accessing environment variables
- oc.select: Selecting an interpolation key, similar to interpolation but more flexible
- oc.dict.{keys,value}: Viewing the keys or the values of a dictionary as a list
Merging configurations¶
Merging configurations enables the creation of reusable configuration files for each logical component instead of a single config file for each variation of your task.
OmegaConf.merge()¶
Machine learning experiment example:
conf = OmegaConf.merge(base_cfg, model_cfg, optimizer_cfg, dataset_cfg)
Web server configuration example:
conf = OmegaConf.merge(server_cfg, plugin1_cfg, site1_cfg, site2_cfg)
The following example creates two configs from files, and one from the cli. It then combines them into a single object. Note how the port changes to 82, and how the users lists are combined.
example2.yaml file:
server:
port: 80
users:
- user1
- user2
example3.yaml file:
log:
file: log.txt
>>> from omegaconf import OmegaConf
>>> import sys
>>>
>>> # Simulate command line arguments
>>> sys.argv = ['program.py', 'server.port=82']
>>>
>>> base_conf = OmegaConf.load('source/example2.yaml')
>>> second_conf = OmegaConf.load('source/example3.yaml')
>>> cli_conf = OmegaConf.from_cli()
>>>
>>> # merge them all
>>> conf = OmegaConf.merge(base_conf, second_conf, cli_conf)
>>> print(OmegaConf.to_yaml(conf))
server:
port: 82
users:
- user1
- user2
log:
file: log.txt
OmegaConf.unsafe_merge()¶
OmegaConf offers a second faster function to merge config objects:
conf = OmegaConf.unsafe_merge(base_cfg, model_cfg, optimizer_cfg, dataset_cfg)
Unlike OmegaConf.merge(), unsafe_merge() is destroying the input configs and they should no longer be used after this call. The upside is that it’s substantially faster.
Configuration flags¶
OmegaConf support several configuration flags. Configuration flags can be set on any configuration node (Sequence or Mapping). if a configuration flag is not set it inherits the value from the parent of the node. The default value inherited from the root node is always false.
Read-only flag¶
A read-only configuration cannot be modified. An attempt to modify it will result in omegaconf.ReadonlyConfigError exception
>>> conf = OmegaConf.create({"a": {"b": 10}})
>>> OmegaConf.set_readonly(conf, True)
>>> conf.a.b = 20
Traceback (most recent call last):
...
omegaconf.ReadonlyConfigError: a.b
You can temporarily remove the read only flag from a config object:
>>> conf = OmegaConf.create({"a": {"b": 10}})
>>> OmegaConf.set_readonly(conf, True)
>>> with read_write(conf):
... conf.a.b = 20
>>> conf.a.b
20
Struct flag¶
By default, OmegaConf dictionaries allow write access to unknown fields.
If a field does not exist, writing it will create the field, and attempting to
access the field before creation will raise an exception (either ConfigKeyError
or ConfigAttributeError
, depending on the mode of access).
It’s sometime useful to change this behavior. Using OmegaConf.set_struct
,
it is possible to prevent the creation of fields that do not exist:
>>> conf = OmegaConf.create({"a": {"aa": 10, "bb": 20}})
>>> OmegaConf.set_struct(conf, True)
>>> conf.a.cc = 30
Traceback (most recent call last):
...
omegaconf.errors.ConfigAttributeError: Error setting cc=30 : Key 'cc' in not in struct
full_key: a.cc
reference_type=Any
object_type=dict
You can temporarily remove the struct flag from a config object:
>>> from omegaconf import open_dict
>>> conf = OmegaConf.create({"a": {"aa": 10, "bb": 20}})
>>> OmegaConf.set_struct(conf, True)
>>> with open_dict(conf):
... conf.a.cc = 30
>>> conf.a.cc
30
Utility functions¶
OmegaConf.to_container¶
OmegaConf config objects looks very similar to python dict and list, but in fact are not.
Use OmegaConf.to_container(cfg: Container, resolve: bool)
to convert to a primitive container.
If resolve
is set to True
, interpolations will be resolved during conversion.
>>> conf = OmegaConf.create({"foo": "bar", "foo2": "${foo}"})
>>> assert type(conf) == DictConfig
>>> primitive = OmegaConf.to_container(conf)
>>> show(primitive)
type: dict, value: {'foo': 'bar', 'foo2': '${foo}'}
>>> resolved = OmegaConf.to_container(conf, resolve=True)
>>> show(resolved)
type: dict, value: {'foo': 'bar', 'foo2': 'bar'}
Using throw_on_missing
¶
You can control how missing values are handled by OmegaConf.to_container()
using the throw_on_missing
keyword argument.
>>> conf = OmegaConf.create({"foo": "bar", "missing": "???"})
>>> has_missing = OmegaConf.to_container(conf, throw_on_missing=False)
>>> show(has_missing)
type: dict, value: {'foo': 'bar', 'missing': '???'}
>>> OmegaConf.to_container(conf, throw_on_missing=True)
Traceback (most recent call last):
...
omegaconf.errors.MissingMandatoryValue: Missing mandatory value: missing
full_key: missing
object_type=dict
By default, throw_on_missing=False
.
Setting throw_on_missing=True
can be useful if you want your program to
fail fast when there are missing values in the config.
Using structured_config_mode
¶
You can customize the treatment of OmegaConf.to_container()
for
Structured Config nodes using the structured_config_mode
option.
The default, structured_config_mode=SCMode.DICT
, converts Structured Config nodes to plain dict.
Using structured_config_mode=SCMode.DICT_CONFIG
causes such nodes to remain
as DictConfig
, allowing attribute style access on the resulting node.
Using structured_config_mode=SCMode.INSTANTIATE
, Structured Config nodes
are converted to instances of the backing dataclass or attrs class. Note that
when structured_config_mode=SCMode.INSTANTIATE
, interpolations nested within
a structured config node will be resolved, even if OmegaConf.to_container
is called
with the the keyword argument resolve=False
, so that interpolations are resolved before
being used to instantiate dataclass/attr class instances. Interpolations within
non-structured parent nodes will be resolved (or not) as usual, according to
the resolve
keyword arg.
>>> from omegaconf import SCMode
>>> conf = OmegaConf.create({"structured_config": MyConfig})
>>> container = OmegaConf.to_container(conf,
... structured_config_mode=SCMode.DICT_CONFIG)
>>> show(container)
type: dict, value: {'structured_config': {'port': 80, 'host': 'localhost'}}
>>> show(container["structured_config"])
type: DictConfig, value: {'port': 80, 'host': 'localhost'}
OmegaConf.to_object¶
The OmegaConf.to_object
method recursively converts DictConfig
and ListConfig
objects
into plain Python dicts and lists, with the exception that Structured Config objects are
converted into instances of the backing dataclass or attr class. Interpolations in the config are always resolved by OmegaConf.to_object
.
>>> container = OmegaConf.to_object(conf)
>>> show(container)
type: dict, value: {'structured_config': MyConfig(port=80, host='localhost')}
>>> show(container["structured_config"])
type: MyConfig, value: MyConfig(port=80, host='localhost')
Note that here, container["structured_config"]
is actually an instance of
MyConfig
, whereas in the previous examples we had a dict
or a
DictConfig
object that was duck-typed to look like an instance of
MyConfig
.
The call OmegaConf.to_object(conf)
is equivalent to
OmegaConf.to_container(conf, resolve=True, throw_on_missing=True,
structured_config_mode=SCMode.INSTANTIATE)
.
OmegaConf.resolve¶
def resolve(cfg: Container) -> None:
"""
Resolves all interpolations in the given config object in-place.
:param cfg: An OmegaConf container (DictConfig, ListConfig)
Raises a ValueError if the input object is not an OmegaConf container.
"""
Normally interpolations are resolved lazily, at access time. This function eagerly resolves all interpolations in the given config object in-place. Example:
>>> cfg = OmegaConf.create({"a": 10, "b": "${a}"})
>>> show(cfg)
type: DictConfig, value: {'a': 10, 'b': '${a}'}
>>> assert cfg.a == cfg.b == 10 # lazily resolving interpolation
>>> OmegaConf.resolve(cfg)
>>> show(cfg)
type: DictConfig, value: {'a': 10, 'b': 10}
OmegaConf.select¶
OmegaConf.select()
allows you to select a config node or value, using either a dot-notation or brackets to denote sub-keys.
>>> cfg = OmegaConf.create({
... "foo" : {
... "missing" : "???",
... "bar": {
... "zonk" : 10,
... }
... }
... })
>>> assert OmegaConf.select(cfg, "foo") == {
... "missing" : "???",
... "bar": {
... "zonk" : 10,
... }
... }
>>> assert OmegaConf.select(cfg, "foo.bar") == {
... "zonk" : 10,
... }
>>> assert OmegaConf.select(cfg, "foo.bar.zonk") == 10 # dots
>>> assert OmegaConf.select(cfg, "foo[bar][zonk]") == 10 # brackets
>>> assert OmegaConf.select(cfg, "no_such_key", default=99) == 99
>>> assert OmegaConf.select(cfg, "foo.missing") is None
>>> assert OmegaConf.select(cfg, "foo.missing", default=99) == 99
>>> OmegaConf.select(cfg,
... "foo.missing",
... throw_on_missing=True
... )
Traceback (most recent call last):
...
omegaconf.errors.MissingMandatoryValue: missing node selected
full_key: foo.missing
OmegaConf.update¶
OmegaConf.update()
allows you to update values in your config using either a dot-notation or brackets to denote sub-keys.
The merge flag controls the behavior if the input is a dict
or a list
.
If merge=True
true (the default), dicts and lists are merged instead of being assigned.
The force_add
flag ensures that the path is created even if it will result in insertion of new values into struct nodes.
>>> cfg = OmegaConf.create({"foo" : {"bar": 10}})
>>> OmegaConf.update(cfg, "foo.bar", 20)
>>> assert cfg.foo.bar == 20
>>> # Set dictionary value (using dot notation)
>>> OmegaConf.update(cfg, "foo.bar", {"zonk" : 30}, merge=False)
>>> assert cfg.foo.bar == {"zonk" : 30}
>>> # Merge dictionary value (using bracket notation)
>>> # note that merge is True by default, so you don't really need it here.
>>> OmegaConf.update(cfg, "foo[bar]", {"oompa" : 40}, merge=True)
>>> assert cfg.foo.bar == {"zonk" : 30, "oompa" : 40}
>>> # force_add ignores nodes in struct mode or Structured Configs nodes
>>> # and updates anyway, inserting keys as needed.
>>> OmegaConf.set_struct(cfg, True)
>>> OmegaConf.update(cfg, "a.b.c.d", 10, force_add=True)
>>> assert cfg.a.b.c.d == 10
OmegaConf.masked_copy¶
Creates a copy of a DictConfig
that contains only specific keys.
>>> conf = OmegaConf.create({"a": {"b": 10}, "c":20})
>>> print(OmegaConf.to_yaml(conf))
a:
b: 10
c: 20
>>> c = OmegaConf.masked_copy(conf, ["a"])
>>> print(OmegaConf.to_yaml(c))
a:
b: 10
OmegaConf.is_missing¶
Tests if a value is missing ("???"
).
>>> cfg = OmegaConf.create({
... "foo" : 10,
... "bar": "???"
... })
>>> assert not OmegaConf.is_missing(cfg, "foo")
>>> assert OmegaConf.is_missing(cfg, "bar")
OmegaConf.is_interpolation¶
Tests if a value is an interpolation.
>>> cfg = OmegaConf.create({
... "foo" : 10,
... "bar": "${foo}"
... })
>>> assert not OmegaConf.is_interpolation(cfg, "foo")
>>> assert OmegaConf.is_interpolation(cfg, "bar")
OmegaConf.{is_config, is_dict, is_list}¶
OmegaConf.is_config
tests whether an object is an OmegaConf object (e.g. DictConfig
or ListConfig
).
OmegaConf.is_dict(cfg)
is equivalent to isinstance(cfg, DictConfig)
,
and OmegaConf.is_list(cfg)
is equivalent to isinstance(cfg, ListConfig)
.
>>> # dict:
>>> d = OmegaConf.create({"foo": "bar"})
>>> assert OmegaConf.is_config(d)
>>> assert OmegaConf.is_dict(d)
>>> assert not OmegaConf.is_list(d)
>>> # list:
>>> l = OmegaConf.create([1,2,3])
>>> assert OmegaConf.is_config(l)
>>> assert OmegaConf.is_list(l)
>>> assert not OmegaConf.is_dict(l)
Debugger integration¶
OmegaConf is packaged with a PyDev.Debugger extension which enables better debugging experience in PyCharm, VSCode and other PyDev.Debugger powered IDEs.
- The debugger extension enables OmegaConf-aware object inspection:
- providing information about interpolations.
- properly handling missing values (
"???"
).
- The plugin comes in two flavors:
- USER: Default behavior, useful when debugging your OmegaConf objects.
- DEV: Useful when debugging OmegaConf itself, shows the exact data model of OmegaConf.
The default flavor is USER
. You can select which flavor to use using the environment variable OC_PYDEVD_RESOLVER
,
Which takes the possible values USER
, DEV
and DISABLE
.