OmegaConf.missing_keys to get a set of missing keys

docs/source/usage.rst

@@ -807,6 +807,25 @@ and ``OmegaConf.is_list(cfg)`` is equivalent to ``isinstance(cfg, ListConfig)``.
     >>> assert not OmegaConf.is_dict(l)
 
 
+OmegaConf.missing_keys
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+``OmegaConf.missing_keys(cfg)`` returns a set of missing keys present in the input ``cfg``.
+Each missing key is represented as a ``str``, using a dotlist style.
+This utility function can be used after creating a config object, after merging sources and so on,
+to check for missing mandatory fields and aid in creating a proper error message.
+
+.. doctest::
+
+    >>> missings = OmegaConf.missing_keys({
+    ...     "foo": {"bar": "???"},
+    ...     "missing": "???",
+    ...      "list": ["a", None, "???"]
+    ... })
+    >>> assert missings == {'list[2]', 'foo.bar', 'missing'}
+
+The function raises a `ValueError` on input not representing a config.
+
+
 Debugger integration
 --------------------
 

news/720.feature

@@ -0,0 +1 @@
+New `OmegaConf.missing_keys` method that returns the missing keys in a config object

omegaconf/omegaconf.py

@@ -16,8 +16,10 @@
     Callable,
     Dict,
     Generator,
+    Iterable,
     List,
     Optional,
+    Set,
     Tuple,
     Type,
     Union,
@@ -808,6 +810,34 @@ def resolve(cfg: Container) -> None:
             )
         omegaconf._impl._resolve(cfg)
 
+    @staticmethod
+    def missing_keys(cfg: Any) -> Set[str]:
+        """
+        Returns a set of missing keys in a dotlist style.
+        :param cfg: An `OmegaConf.Container`,
+                    or a convertible object via `OmegaConf.create` (dict, list, ...).
+        :return: set of strings of the missing keys.
+        :raises ValueError: On input not representing a config.
+        """
+        cfg = _ensure_container(cfg)
+        missings: Set[str] = set()
+
+        def gather(_cfg: Container) -> None:
+            itr: Iterable[Any]
+            if isinstance(_cfg, ListConfig):
+                itr = range(len(_cfg))
+            else:
+                itr = _cfg
+
+            for key in itr:
+                if OmegaConf.is_missing(_cfg, key):
+                    missings.add(_cfg._get_full_key(key))
+                elif OmegaConf.is_config(_cfg[key]):
+                    gather(_cfg[key])
+
+        gather(cfg)
+        return missings
+
     # === private === #
 
     @staticmethod
@@ -930,7 +960,6 @@ def flag_override(
     names: Union[List[str], str],
     values: Union[List[Optional[bool]], Optional[bool]],
 ) -> Generator[Node, None, None]:
-
     if isinstance(names, str):
         names = [names]
     if values is None or isinstance(values, bool):

tests/test_omegaconf.py

@@ -520,6 +520,95 @@ def test_resolve_invalid_input() -> None:
         OmegaConf.resolve("aaa")  # type: ignore
 
 
+@mark.parametrize(
+    "cfg, expected",
+    [
+        # dict:
+        ({"a": 10, "b": {"c": "???", "d": "..."}}, {"b.c"}),
+        (
+            {
+                "a": "???",
+                "b": {
+                    "foo": "bar",
+                    "bar": "???",
+                    "more": {"missing": "???", "available": "yes"},
+                },
+                Color.GREEN: {"tint": "???", "default": Color.BLUE},
+            },
+            {"a", "b.bar", "b.more.missing", "GREEN.tint"},
+        ),
+        (
+            {"a": "a", "b": {"foo": "bar", "bar": "foo"}},
+            set(),
+        ),
+        (
+            {"foo": "bar", "bar": "???", "more": {"foo": "???", "bar": "foo"}},
+            {"bar", "more.foo"},
+        ),
+        # list:
+        (["???", "foo", "bar", "???", 77], {"[0]", "[3]"}),
+        (["", "foo", "bar"], set()),
+        (["foo", "bar", "???"], {"[2]"}),
+        (["foo", "???", ["???", "bar"]], {"[1]", "[2][0]"}),
+        # mixing:
+        (
+            [
+                "???",
+                "foo",
+                {
+                    "a": True,
+                    "b": "???",
+                    "c": ["???", None],
+                    "d": {"e": "???", "f": "fff", "g": [True, "???"]},
+                },
+                "???",
+                77,
+            ],
+            {"[0]", "[2].b", "[2].c[0]", "[2].d.e", "[2].d.g[1]", "[3]"},
+        ),
+        (
+            {
+                "list": [
+                    0,
+                    DictConfig({"foo": "???", "bar": None}),
+                    "???",
+                    ["???", 3, False],
+                ],
+                "x": "y",
+                "y": "???",
+            },
+            {"list[1].foo", "list[2]", "list[3][0]", "y"},
+        ),
+        ({Color.RED: ["???", {"missing": "???"}]}, {"RED[0]", "RED[1].missing"}),
+        # with DictConfig and ListConfig:
+        (
+            DictConfig(
+                {
+                    "foo": "???",
+                    "list": ["???", 1],
+                    "bar": {"missing": "???", "more": "yes"},
+                }
+            ),
+            {"foo", "list[0]", "bar.missing"},
+        ),
+        (
+            ListConfig(
+                ["???", "yes", "???", [0, 1, "???"], {"missing": "???", "more": ""}],
+            ),
+            {"[0]", "[2]", "[3][2]", "[4].missing"},
+        ),
+    ],
+)
+def test_missing_keys(cfg: Any, expected: Any) -> None:
+    assert OmegaConf.missing_keys(cfg) == expected
+
+
+@mark.parametrize("cfg", [float, int])
+def test_missing_keys_invalid_input(cfg: Any) -> None:
+    with raises(ValueError):
+        OmegaConf.missing_keys(cfg)
+
+
 @mark.parametrize(
     ("register_resolver_params", "name", "expected"),
     [