How to type a config item that can be both a list or dict?

[pawamoy]

On Python 3.10 it looks like we can do Type(list | dict). This won't work on Python 3.8 and 3.9.

[pawamoy]

I suppose we have to subclass Type, like Plugins does:

class Plugins(OptionallyRequired[plugins.PluginCollection]):
    def run_validation(self, value: object) -> plugins.PluginCollection:
        if not isinstance(value, (list, tuple, dict)):
            raise ValidationError('Invalid Plugins configuration. Expected a list or dict.')

So something like:

class ListOrDict(Type[Union[list, dict]]):
    def run_validation(self, value: object) -> ...:
        if not isinstance(value, (list, tuple, dict)):
            raise ValidationError('Invalid configuration. Expected a list or dict.')

[oprypin]

Type((list, dict)) is a supported way to write this.

mkdocs/mkdocs/config/config_options.py

Line 331 in 00b648f

def __init__(self, type_: tuple[type[T], ...], length: int | None = None, **kwargs):

---

Type(list | dict) works by accident only on newer versions of Python at run time

but does not pass mypy:

 error: No overload variant of "Type" matches argument type "UnionType"  [call-overload]
 note: Possible overload variants:
 note:     def [T] __init__(self, type_: type[T], length: int | None = ..., **kwargs: Any) -> Type[T]
 note:     def [T] __init__(self, type_: tuple[type[T], ...], length: int | None = ..., **kwargs: Any) -> Type[T]

---

Note also that if you find yourself allowing both list | dict, the config could probably use a more specific implementation that's much more useful for type checking.
For example:

class ListOfItemsThatCanBeWrittenAsDict(BaseConfigOption[List[MyItem]]):
    def run_validation(self, value: object) -> plugins.PluginCollection:
        if not isinstance(value, (list, dict)):
            raise ValidationError('Invalid configuration. Expected a list or dict.')
        if isinstance(value, dict):
            return [MyItem(name=k, **v) for k, v in value.items()]
        else:
            return [MyItem(**v) for v in value]

As a further note, MyItem here could itself probably use a sub-implementation as a Config, otherwise this code is still missing a lot of error checking implementation.
For example, see here how to implement an item that's fully type checked and should be specified as a dict but can alternatively be written out as just one string instead

mkdocs/mkdocs/config/config_options.py

Line 948 in 00b648f

class ExtraScript(BaseConfigOption[Union[ExtraScriptValue, str]]):

[pawamoy]

Ah, I was sure there was a way to do this (I had seen this previously) but couldn't find any examples in the docs or my own projects! I missed the overload and the tuple with ellipsis in MkDocs' code 😅

Thanks for the reminder and for the detailed code examples 🙂