Add DictOfItems type for configuration options (#3242)

mkdocs/config/config_options.py

@@ -13,6 +13,7 @@ from typing import (
     Any,
     Callable,
     Collection,
+    Dict,
     Generic,
     Iterator,
     List,
@@ -199,6 +200,63 @@ class ListOfItems(Generic[T], BaseConfigOption[List[T]]):
         return [fake_config[k] for k in fake_keys]
 
 
+class DictOfItems(Generic[T], BaseConfigOption[Dict[str, T]]):
+    """
+    Validates a dict of items. Keys are always strings.
+
+    E.g. for `config_options.DictOfItems(config_options.Type(int))` a valid item is `{"a": 1, "b": 2}`.
+    """
+
+    required: bool | None = None  # Only for subclasses to set.
+
+    def __init__(self, option_type: BaseConfigOption[T], default=None) -> None:
+        super().__init__()
+        self.default = default
+        self.option_type = option_type
+        self.option_type.warnings = self.warnings
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}: {self.option_type}"
+
+    def pre_validation(self, config: Config, key_name: str):
+        self._config = config
+        self._key_name = key_name
+
+    def run_validation(self, value: object) -> Dict[str, T]:
+        if value is None:
+            if self.required or self.default is None:
+                raise ValidationError("Required configuration not provided.")
+            value = self.default
+        if not isinstance(value, dict):
+            raise ValidationError(f"Expected a dict of items, but a {type(value)} was given.")
+        if not value:  # Optimization for empty list
+            return value
+
+        fake_config = LegacyConfig(())
+        try:
+            fake_config.config_file_path = self._config.config_file_path
+        except AttributeError:
+            pass
+
+        # Emulate a config-like environment for pre_validation and post_validation.
+        fake_config.data = value
+
+        for key in fake_config:
+            self.option_type.pre_validation(fake_config, key)
+        for key in fake_config:
+            if not isinstance(key, str):
+                raise ValidationError(
+                    f"Expected type: {str} for keys, but received: {type(key)} (key={key})"
+                )
+        for key in fake_config:
+            # Specifically not running `validate` to avoid the OptionallyRequired effect.
+            fake_config[key] = self.option_type.run_validation(fake_config[key])
+        for key in fake_config:
+            self.option_type.post_validation(fake_config, key)
+
+        return value
+
+
 class ConfigItems(ListOfItems[LegacyConfig]):
     """
     Deprecated: Use `ListOfItems(SubConfig(...))` instead of `ConfigItems(...)`.

mkdocs/tests/config/config_options_tests.py

@@ -679,6 +679,111 @@ class ListOfItemsTest(TestCase):
             self.get_config(Schema, {'option': ["localhost:8000", "1.2.3.4:asdf"]})
 
 
+class DictOfItemsTest(TestCase):
+    def test_int_type(self) -> None:
+        class Schema(Config):
+            option = c.DictOfItems(c.Type(int))
+
+        conf = self.get_config(Schema, {'option': {"a": 1, "b": 2}})
+        assert_type(conf.option, Dict[str, int])
+        self.assertEqual(conf.option, {"a": 1, "b": 2})
+
+        with self.expect_error(
+            option="Expected type: <class 'int'> but received: <class 'NoneType'>"
+        ):
+            conf = self.get_config(Schema, {'option': {"a": 1, "b": None}})
+
+    def test_combined_float_type(self) -> None:
+        class Schema(Config):
+            option = c.DictOfItems(c.Type((int, float)))
+
+        conf = self.get_config(Schema, {'option': {"a": 1, "b": 2.3}})
+        self.assertEqual(conf.option, {"a": 1, "b": 2.3})
+
+        with self.expect_error(
+            option="Expected type: (<class 'int'>, <class 'float'>) but received: <class 'str'>"
+        ):
+            self.get_config(Schema, {'option': {"a": 1, "b": "2"}})
+
+    def test_dict_default(self) -> None:
+        class Schema(Config):
+            option = c.DictOfItems(c.Type(int), default={})
+
+        conf = self.get_config(Schema, {})
+        assert_type(conf.option, Dict[str, int])
+        self.assertEqual(conf.option, {})
+
+        with self.expect_error(option="Required configuration not provided."):
+            conf = self.get_config(Schema, {'option': None})
+
+    def test_none_without_default(self) -> None:
+        class Schema(Config):
+            option = c.DictOfItems(c.Type(str))
+
+        with self.expect_error(option="Required configuration not provided."):
+            conf = self.get_config(Schema, {})
+
+        with self.expect_error(option="Required configuration not provided."):
+            conf = self.get_config(Schema, {'option': None})
+
+        conf = self.get_config(Schema, {'option': {"foo": "bar"}})
+        self.assertEqual(conf.option, {"foo": "bar"})
+
+    def test_optional(self) -> None:
+        class Schema(Config):
+            option = c.Optional(c.DictOfItems(c.Type(str)))
+
+        conf = self.get_config(Schema, {})
+        assert_type(conf.option, Optional[Dict[str, str]])
+        self.assertEqual(conf.option, None)
+
+        conf = self.get_config(Schema, {'option': None})
+        self.assertEqual(conf.option, None)
+
+        conf = self.get_config(Schema, {'option': {"foo": "bar"}})
+        self.assertEqual(conf.option, {"foo": "bar"})
+
+    def test_dict_of_optional(self) -> None:
+        class Schema(Config):
+            option = c.DictOfItems(c.Optional(c.Type(int)), default={})
+
+        conf = self.get_config(Schema, {})
+        assert_type(conf.option, Dict[str, Optional[int]])
+        self.assertEqual(conf.option, {})
+
+        conf = self.get_config(Schema, {'option': {"a": 1, "b": None}})
+        self.assertEqual(conf.option, {"a": 1, "b": None})
+
+        with self.expect_error(option="Expected type: <class 'int'> but received: <class 'str'>"):
+            conf = self.get_config(Schema, {'option': {"foo": "bar"}})
+            self.assertEqual(conf.option, {"foo": "bar"})
+
+    def test_string_not_a_dict_of_strings(self) -> None:
+        class Schema(Config):
+            option = c.DictOfItems(c.Type(str))
+
+        with self.expect_error(option="Expected a dict of items, but a <class 'str'> was given."):
+            self.get_config(Schema, {'option': 'foo'})
+
+    def test_post_validation_error(self) -> None:
+        class Schema(Config):
+            option = c.DictOfItems(c.IpAddress())
+
+        with self.expect_error(option="'asdf' is not a valid port"):
+            self.get_config(
+                Schema, {'option': {"ip_foo": "localhost:8000", "ip_bar": "1.2.3.4:asdf"}}
+            )
+
+    def test_all_keys_are_strings(self) -> None:
+        class Schema(Config):
+            option = c.DictOfItems(c.Type(int))
+
+        with self.expect_error(
+            option="Expected type: <class 'str'> for keys, but received: <class 'int'> (key=2)"
+        ):
+            self.get_config(Schema, {'option': {"a": 1, 2: 3}})
+
+
 class FilesystemObjectTest(TestCase):
     def test_valid_dir(self) -> None:
         for cls in c.Dir, c.FilesystemObject: