to_container: replace exclude_structured_configs with SCMode

Closes omry#548

omegaconf/__init__.py

@@ -1,4 +1,4 @@
-from .base import Container, DictKeyType, Node
+from .base import Container, DictKeyType, Node, SCMode
 from .dictconfig import DictConfig
 from .errors import (
     KeyValidationError,
@@ -42,6 +42,7 @@
     "DictKeyType",
     "OmegaConf",
     "Resolver",
+    "SCMode",
     "flag_override",
     "read_write",
     "open_dict",

omegaconf/base.py

@@ -615,3 +615,9 @@ def _invalidate_flags_cache(self) -> None:
 
     def _has_ref_type(self) -> bool:
         return self._metadata.ref_type is not Any
+
+
+class SCMode(Enum):
+    DICT = 1  # convert to plain dict
+    DICT_CONFIG = 2  # Keep as OmegaConf DictConfig
+    INSTANTIATE = 3  # instantiate underlying object.

omegaconf/basecontainer.py

@@ -25,7 +25,7 @@
     is_primitive_type,
     is_structured_config,
 )
-from .base import Container, ContainerMetadata, DictKeyType, Node
+from .base import Container, ContainerMetadata, DictKeyType, Node, SCMode
 from .errors import MissingMandatoryValue, ReadonlyConfigError, ValidationError
 
 if TYPE_CHECKING:
@@ -192,11 +192,14 @@ def _to_content(
         conf: Container,
         resolve: bool,
         enum_to_str: bool = False,
-        exclude_structured_configs: bool = False,
+        structured_config_mode: SCMode = SCMode.DICT,
     ) -> Union[None, Any, str, Dict[DictKeyType, Any], List[Any]]:
         from .dictconfig import DictConfig
         from .listconfig import ListConfig
 
+        if structured_config_mode == SCMode.INSTANTIATE:
+            raise NotImplementedError("wip in PR #502")
+
         def convert(val: Node) -> Any:
             value = val._value()
             if enum_to_str and isinstance(value, Enum):
@@ -214,7 +217,10 @@ def convert(val: Node) -> Any:
         elif conf._is_missing():
             return "???"
         elif isinstance(conf, DictConfig):
-            if conf._metadata.object_type is not None and exclude_structured_configs:
+            if (
+                conf._metadata.object_type is not None
+                and structured_config_mode == SCMode.DICT_CONFIG
+            ):
                 return conf
 
             retdict: Dict[str, Any] = {}
@@ -232,7 +238,7 @@ def convert(val: Node) -> Any:
                         node,
                         resolve=resolve,
                         enum_to_str=enum_to_str,
-                        exclude_structured_configs=exclude_structured_configs,
+                        structured_config_mode=structured_config_mode,
                     )
                 else:
                     retdict[key] = convert(node)
@@ -252,7 +258,7 @@ def convert(val: Node) -> Any:
                         node,
                         resolve=resolve,
                         enum_to_str=enum_to_str,
-                        exclude_structured_configs=exclude_structured_configs,
+                        structured_config_mode=structured_config_mode,
                     )
                     retlist.append(item)
                 else:

omegaconf/omegaconf.py

@@ -47,7 +47,7 @@
     is_tuple_annotation,
     type_str,
 )
-from .base import Container, Node
+from .base import Container, Node, SCMode
 from .basecontainer import BaseContainer
 from .errors import (
     ConfigKeyError,
@@ -579,7 +579,8 @@ def to_container(
         *,
         resolve: bool = False,
         enum_to_str: bool = False,
-        exclude_structured_configs: bool = False,
+        structured_config_mode: SCMode = SCMode.DICT,
+        exclude_structured_configs: Optional[bool] = None,
     ) -> Union[Dict[DictKeyType, Any], List[Any], None, str]:
         """
         Resursively converts an OmegaConf config to a primitive container (dict or list).
@@ -590,6 +591,19 @@ def to_container(
                (DictConfigs backed by a dataclass)
         :return: A dict or a list representing this config as a primitive container.
         """
+        if exclude_structured_configs is not None:
+            warnings.warn(
+                dedent(
+                    """\
+                The exclude_structured_configs argument to to_container is deprecated.
+                See https://github.com/omry/omegaconf/issues/548 for migration instructions.
+                """
+                ),
+                DeprecationWarning,
+                stacklevel=2,
+            )
+            if exclude_structured_configs is True:
+                structured_config_mode = SCMode.DICT_CONFIG
         if not OmegaConf.is_config(cfg):
             raise ValueError(
                 f"Input cfg is not an OmegaConf config object ({type_str(type(cfg))})"
@@ -599,7 +613,7 @@ def to_container(
             cfg,
             resolve=resolve,
             enum_to_str=enum_to_str,
-            exclude_structured_configs=exclude_structured_configs,
+            structured_config_mode=structured_config_mode,
         )
 
     @staticmethod

tests/test_to_container.py

@@ -4,7 +4,7 @@
 
 import pytest
 
-from omegaconf import DictConfig, ListConfig, OmegaConf
+from omegaconf import DictConfig, ListConfig, OmegaConf, SCMode
 from tests import Color, User
 
 
@@ -39,7 +39,7 @@ def assert_container_with_primitives(item: Any) -> None:
 
 
 @pytest.mark.parametrize(
-    "cfg,ex_false,ex_true",
+    "src,ex_DICT,ex_DICT_CONFIG",
     [
         pytest.param(
             {"user": User(age=7, name="Bond")},
@@ -58,13 +58,38 @@ def assert_container_with_primitives(item: Any) -> None:
         ),
     ],
 )
-def test_exclude_structured_configs(cfg: Any, ex_false: Any, ex_true: Any) -> None:
-    cfg = OmegaConf.create(cfg)
-    ret1 = OmegaConf.to_container(cfg, exclude_structured_configs=False)
-    assert ret1 == ex_false
-
-    ret1 = OmegaConf.to_container(cfg, exclude_structured_configs=True)
-    assert ret1 == ex_true
+class TestSCMode:
+    @pytest.fixture
+    def cfg(self, src: Any) -> Any:
+        return OmegaConf.create(src)
+
+    def test_exclude_structured_configs_default(
+        self, cfg: Any, ex_DICT: Any, ex_DICT_CONFIG: Any
+    ) -> None:
+        ret = OmegaConf.to_container(cfg)
+        assert ret == ex_DICT
+
+    def test_SCMode_DICT(self, cfg: Any, ex_DICT: Any, ex_DICT_CONFIG: Any) -> None:
+        ret = OmegaConf.to_container(cfg, structured_config_mode=SCMode.DICT)
+        assert ret == ex_DICT
+        with pytest.deprecated_call():
+            ret = OmegaConf.to_container(cfg, exclude_structured_configs=False)
+        assert ret == ex_DICT
+
+    def test_SCMode_DICT_CONFIG(
+        self, cfg: Any, ex_DICT: Any, ex_DICT_CONFIG: Any
+    ) -> None:
+        ret = OmegaConf.to_container(cfg, structured_config_mode=SCMode.DICT_CONFIG)
+        assert ret == ex_DICT_CONFIG
+        with pytest.deprecated_call():
+            ret = OmegaConf.to_container(cfg, exclude_structured_configs=True)
+        assert ret == ex_DICT_CONFIG
+
+    def test_SCMode_INSTANTIATE(
+        self, cfg: Any, ex_DICT: Any, ex_DICT_CONFIG: Any
+    ) -> None:
+        with pytest.raises(NotImplementedError):  # wip in #502
+            OmegaConf.to_container(cfg, structured_config_mode=SCMode.INSTANTIATE)
 
 
 @pytest.mark.parametrize(