OmegaConf.to_object: Instantiate structured configs

docs/source/usage.rst

@@ -776,6 +776,11 @@ Structured Config nodes using the ``structured_config_mode`` option.
 By default, Structured Config nodes are converted 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
+typically ``structured_config_mode=SCMode.INSTANTIATE`` makes the most sense
+when combined with ``resolve=True``, so that interpolations are resolved before
+being used to instantiate dataclass/attr class instances.
 
 .. doctest::
 
@@ -788,6 +793,30 @@ as DictConfig, allowing attribute style access on the resulting node.
     >>> 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 dicts and lists, with the exception that Structured Config objects are
+converted into instances of the backing dataclass or attr class.  All OmegaConf
+interpolations are resolved before conversion to Python containers.
+
+.. doctest::
+
+    >>> 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,
+structured_config_mode=SCMode.INSTANTIATE)``.
+
 OmegaConf.resolve
 ^^^^^^^^^^^^^^^^^
 .. code-block:: python

news/472.feature

@@ -0,0 +1 @@
+Add the OmegaConf.to_object method, which converts Structured Config objects back to native dataclasses or attrs classes.

omegaconf/_utils.py

@@ -201,6 +201,12 @@ def _resolve_forward(type_: Type[Any], module: str) -> Type[Any]:
         return type_
 
 
+def get_attr_class_field_names(obj: Any) -> List[str]:
+    is_type = isinstance(obj, type)
+    obj_type = obj if is_type else type(obj)
+    return list(attr.fields_dict(obj_type))
+
+
 def get_attr_data(obj: Any, allow_objects: Optional[bool] = None) -> Dict[str, Any]:
     from omegaconf.omegaconf import OmegaConf, _maybe_wrap
 
@@ -240,6 +246,10 @@ def get_attr_data(obj: Any, allow_objects: Optional[bool] = None) -> Dict[str, A
     return d
 
 
+def get_dataclass_field_names(obj: Any) -> List[str]:
+    return [field.name for field in dataclasses.fields(obj)]
+
+
 def get_dataclass_data(
     obj: Any, allow_objects: Optional[bool] = None
 ) -> Dict[str, Any]:
@@ -332,6 +342,15 @@ def is_structured_config_frozen(obj: Any) -> bool:
     return False
 
 
+def get_structured_config_field_names(obj: Any) -> List[str]:
+    if is_dataclass(obj):
+        return get_dataclass_field_names(obj)
+    elif is_attr_class(obj):
+        return get_attr_class_field_names(obj)
+    else:
+        raise ValueError(f"Unsupported type: {type(obj).__name__}")
+
+
 def get_structured_config_data(
     obj: Any, allow_objects: Optional[bool] = None
 ) -> Dict[str, Any]:

omegaconf/base.py

@@ -728,5 +728,6 @@ def _has_ref_type(self) -> bool:
 
 
 class SCMode(Enum):
-    DICT = 1  # convert to plain dict
+    DICT = 1  # Convert to plain dict
     DICT_CONFIG = 2  # Keep as OmegaConf DictConfig
+    INSTANTIATE = 3  # Create a dataclass or attrs class instance

omegaconf/basecontainer.py

@@ -214,7 +214,7 @@ def convert(val: Node) -> Any:
             ):
                 return conf
 
-            retdict: Dict[str, Any] = {}
+            ret: Any = {}
             for key in conf.keys():
                 node = conf._get_node(key)
                 assert isinstance(node, Node)
@@ -225,15 +225,20 @@ def convert(val: Node) -> Any:
                 if enum_to_str and isinstance(key, Enum):
                     key = f"{key.name}"
                 if isinstance(node, Container):
-                    retdict[key] = BaseContainer._to_content(
+                    ret[key] = BaseContainer._to_content(
                         node,
                         resolve=resolve,
                         enum_to_str=enum_to_str,
                         structured_config_mode=structured_config_mode,
                     )
                 else:
-                    retdict[key] = convert(node)
-            return retdict
+                    ret[key] = convert(node)
+
+            if structured_config_mode == SCMode.INSTANTIATE and is_structured_config(
+                conf._metadata.object_type
+            ):
+                ret = conf._instantiate_structured_config_impl(instance_data=ret)
+            return ret
         elif isinstance(conf, ListConfig):
             retlist: List[Any] = []
             for index in range(len(conf)):
@@ -257,6 +262,34 @@ def convert(val: Node) -> Any:
 
         assert False
 
+    def _instantiate_structured_config_impl(self, instance_data: Dict[str, Any]) -> Any:
+        """Instantiate an instance of `self._metadata.object_type`, populated by `instance_data`."""
+        from ._utils import get_structured_config_field_names
+
+        object_type = self._metadata.object_type
+        object_type_field_names = set(get_structured_config_field_names(object_type))
+
+        field_items: Dict[str, Any] = {}
+        nonfield_items: Dict[str, Any] = {}
+        for k, v in instance_data.items():
+            if _is_missing_literal(v):
+                self._format_and_raise(
+                    key=k,
+                    value=None,
+                    cause=MissingMandatoryValue(
+                        "Structured config of type `$OBJECT_TYPE` has missing mandatory value: $KEY"
+                    ),
+                )
+            if k in object_type_field_names:
+                field_items[k] = v
+            else:
+                nonfield_items[k] = v
+
+        result = object_type(**field_items)
+        for k, v in nonfield_items.items():
+            setattr(result, k, v)
+        return result
+
     def pretty(self, resolve: bool = False, sort_keys: bool = False) -> str:
         from omegaconf import OmegaConf
 

omegaconf/omegaconf.py

@@ -580,6 +580,9 @@ def to_container(
         :param 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.
         :return: A dict or a list representing this config as a primitive container.
         """
         if not OmegaConf.is_config(cfg):
@@ -594,6 +597,30 @@ def to_container(
             structured_config_mode=structured_config_mode,
         )
 
+    @staticmethod
+    def to_object(
+        cfg: Any,
+        *,
+        enum_to_str: bool = False,
+    ) -> Union[Dict[DictKeyType, Any], List[Any], None, str, Any]:
+        """
+        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, structured_config_mode=SCMode.INSTANTIATE)
+
+        :param cfg: the config to convert
+        :param enum_to_str: True to convert Enum values to strings
+        :return: A dict or a list or dataclass representing this config.
+        """
+        return OmegaConf.to_container(
+            cfg=cfg,
+            resolve=True,
+            enum_to_str=enum_to_str,
+            structured_config_mode=SCMode.INSTANTIATE,
+        )
+
     @staticmethod
     def is_missing(cfg: Any, key: DictKeyType) -> bool:
         assert isinstance(cfg, Container)

tests/structured_conf/data/attr_classes.py

@@ -440,6 +440,10 @@ class Str2StrWithField(Dict[str, str]):
     class Str2IntWithStrField(Dict[str, int]):
         foo: int = 1
 
+    @attr.s(auto_attribs=True)
+    class Str2UserWithField(Dict[str, User]):
+        foo: User = User("Bond", 7)
+
     class Error:
         @attr.s(auto_attribs=True)
         class User2Str(Dict[User, str]):

tests/structured_conf/data/dataclasses.py

@@ -461,6 +461,10 @@ class Str2StrWithField(Dict[str, str]):
     class Str2IntWithStrField(Dict[str, int]):
         foo: int = 1
 
+    @dataclass
+    class Str2UserWithField(Dict[str, User]):
+        foo: User = User("Bond", 7)
+
     class Error:
         @dataclass
         class User2Str(Dict[User, str]):

tests/test_errors.py

@@ -1234,6 +1234,18 @@ def finalize(self, cfg: Any) -> None:
         ),
         id="list,readonly:del",
     ),
+    # to_object
+    param(
+        Expected(
+            create=lambda: OmegaConf.structured(User),
+            op=lambda cfg: OmegaConf.to_object(cfg),
+            exception_type=MissingMandatoryValue,
+            msg="Structured config of type `User` has missing mandatory value: name",
+            key="name",
+            child_node=lambda cfg: cfg._get_node("name"),
+        ),
+        id="to_object:structured-missing-field",
+    ),
 ]