Adds literal node

.pre-commit-config.yaml

@@ -21,4 +21,4 @@ repos:
     hooks:
       - id: mypy
         args: [--strict]
-        additional_dependencies: ['pytest']
+        additional_dependencies: ['pytest', 'types-dataclasses']

omegaconf/__init__.py

@@ -14,6 +14,7 @@
     EnumNode,
     FloatNode,
     IntegerNode,
+    LiteralNode,
     StringNode,
     ValueNode,
 )
@@ -53,6 +54,7 @@
     "StringNode",
     "BooleanNode",
     "EnumNode",
+    "LiteralNode",
     "FloatNode",
     "MISSING",
     "SI",

omegaconf/_utils.py

@@ -43,6 +43,11 @@
 except ImportError:  # pragma: no cover
     attr = None  # type: ignore # pragma: no cover
 
+if sys.version_info >= (3, 8):
+    from typing import Literal  # pragma: no cover
+else:
+    from typing_extensions import Literal  # pragma: no cover
+
 
 # Regexprs to match key paths like: a.b, a[b], ..a[c].d, etc.
 # We begin by matching the head (in these examples: a, a, ..a).
@@ -593,6 +598,20 @@ def is_tuple_annotation(type_: Any) -> bool:
         return origin is tuple  # pragma: no cover
 
 
+def is_literal_annotation(type_: Any) -> bool:
+    origin = getattr(type_, "__origin__", None)
+    if sys.version_info >= (3, 8, 0):
+        return origin is Literal  # pragma: no cover
+    else:
+        return (
+            origin is Literal
+            or type_ is Literal
+            or (
+                "typing_extensions.Literal" in str(type_) and not isinstance(type_, str)
+            )
+        )  # pragma: no cover
+
+
 def is_dict_subclass(type_: Any) -> bool:
     return type_ is not None and isinstance(type_, type) and issubclass(type_, Dict)
 
@@ -822,13 +841,21 @@ def type_str(t: Any, include_module_name: bool = False) -> str:
         return "Any"
     if t is ...:
         return "..."
+    if (
+        isinstance(t, int)
+        or isinstance(t, str)
+        or isinstance(t, bytes)
+        or isinstance(t, Enum)
+    ):
+        # only occurs when using typing.Literal after 3.8
+        return str(t)  # pragma: no cover
 
     if sys.version_info < (3, 7, 0):  # pragma: no cover
         # Python 3.6
         if hasattr(t, "__name__"):
             name = str(t.__name__)
         else:
-            if t.__origin__ is not None:
+            if hasattr(t, "__origin__") and t.__origin__ is not None:
                 name = type_str(t.__origin__)
             else:
                 name = str(t)

omegaconf/nodes.py

@@ -10,6 +10,7 @@
     _is_interpolation,
     get_type_of,
     get_value_kind,
+    is_literal_annotation,
     is_primitive_container,
     type_str,
 )
@@ -400,6 +401,62 @@ def __deepcopy__(self, memo: Dict[int, Any]) -> "EnumNode":
         return res
 
 
+class LiteralNode(ValueNode):
+    def __init__(
+        self,
+        literal_type: Any,  # cannot Type[Literal] because Literal requires an argument
+        value: Optional[Union[Enum, str, int, bool]] = None,
+        key: Any = None,
+        parent: Optional[Container] = None,
+        is_optional: bool = True,
+        flags: Optional[Dict[str, bool]] = None,
+    ):
+        if not is_literal_annotation(literal_type):
+            raise ValidationError(
+                f"LiteralNode can only operate on Literal annotation ({literal_type})"
+            )
+        self.literal_type = literal_type
+        if hasattr(self.literal_type, "__args__"):
+            self.fields = list(self.literal_type.__args__)  # pragma: no cover
+        elif hasattr(self.literal_type, "__values__"):  # pragma: no cover
+            self.fields = list(self.literal_type.__values__)  # pragma: no cover
+        super().__init__(
+            parent=parent,
+            value=value,
+            metadata=Metadata(
+                key=key,
+                optional=is_optional,
+                ref_type=literal_type,
+                object_type=literal_type,
+                flags=flags,
+            ),
+        )
+
+    def _validate_and_convert_impl(self, value: Any) -> Any:
+        return self.validate_and_convert_to_literal(
+            enum_type=self.literal_type, value=value
+        )
+
+    def validate_and_convert_to_literal(self, enum_type: Type[Enum], value: Any) -> Any:
+        if value not in self.fields:
+            raise ValidationError(
+                f"Value $VALUE ($VALUE_TYPE) is not a valid input for {enum_type}"
+            )
+        index = self.fields.index(value)
+        if not isinstance(value, type(self.fields[index])):
+            raise ValidationError(
+                f"Value $VALUE ($VALUE_TYPE) is not a valid input for {enum_type} because "
+                f"type(value)={type(value)} but the matching literal value's type={type(self.fields[index])}"
+            )
+
+        return value
+
+    def __deepcopy__(self, memo: Dict[int, Any]) -> "LiteralNode":
+        res = LiteralNode(literal_type=self.literal_type)
+        self._deepcopy_impl(res, memo)
+        return res
+
+
 class InterpolationResultNode(ValueNode):
     """
     Special node type, used to wrap interpolation results.

omegaconf/omegaconf.py

@@ -43,6 +43,7 @@
     is_dict_annotation,
     is_int,
     is_list_annotation,
+    is_literal_annotation,
     is_primitive_container,
     is_primitive_dict,
     is_primitive_list,
@@ -66,6 +67,7 @@
     EnumNode,
     FloatNode,
     IntegerNode,
+    LiteralNode,
     StringNode,
     ValueNode,
 )
@@ -1046,6 +1048,14 @@ def _node_wrap(
         )
     elif type_ == Any or type_ is None:
         node = AnyNode(value=value, key=key, parent=parent)
+    elif is_literal_annotation(type_):
+        node = LiteralNode(
+            literal_type=type_,
+            value=value,
+            key=key,
+            parent=parent,
+            is_optional=is_optional,
+        )
     elif issubclass(type_, Enum):
         node = EnumNode(
             enum_type=type_,

tests/structured_conf/data/attr_classes.py

@@ -8,7 +8,9 @@
 from tests import Color
 
 if sys.version_info >= (3, 8):  # pragma: no cover
-    from typing import TypedDict
+    from typing import Literal, TypedDict
+else:
+    from typing_extensions import Literal
 
 # attr is a dependency of pytest which means it's always available when testing with pytest.
 importorskip("attr")
@@ -169,6 +171,23 @@ class EnumConfig:
     interpolation: Color = II("with_default")
 
 
+@attr.s(auto_attribs=True)
+class LiteralConfig:
+    # with default value
+    with_default: Literal["foo", "bar", True, b"baz", 5, Color.GREEN] = "foo"
+
+    # default is None
+    null_default: Optional[Literal["foo", "bar", True, b"baz", 5, Color.GREEN]] = None
+
+    # explicit no default
+    mandatory_missing: Literal["foo", "bar", True, b"baz", 5, Color.GREEN] = MISSING
+
+    # interpolation, will inherit the type and value of `with_default'
+    interpolation: Literal["foo", "bar", True, b"baz", 5, Color.GREEN] = II(
+        "with_default"
+    )
+
+
 @attr.s(auto_attribs=True)
 class ConfigWithList:
     list1: List[int] = [1, 2, 3]

tests/structured_conf/data/dataclasses.py

@@ -9,7 +9,9 @@
 from tests import Color
 
 if sys.version_info >= (3, 8):  # pragma: no cover
-    from typing import TypedDict
+    from typing import Literal, TypedDict
+else:
+    from typing_extensions import Literal
 
 # skip test if dataclasses are not available
 importorskip("dataclasses")
@@ -170,6 +172,23 @@ class EnumConfig:
     interpolation: Color = II("with_default")
 
 
+@dataclass
+class LiteralConfig:
+    # with default value
+    with_default: Literal["foo", "bar", True, b"baz", 5, Color.GREEN] = "foo"
+
+    # default is None
+    null_default: Optional[Literal["foo", "bar", True, b"baz", 5, Color.GREEN]] = None
+
+    # explicit no default
+    mandatory_missing: Literal["foo", "bar", True, b"baz", 5, Color.GREEN] = MISSING
+
+    # interpolation, will inherit the type and value of `with_default'
+    interpolation: Literal["foo", "bar", True, b"baz", 5, Color.GREEN] = II(
+        "with_default"
+    )
+
+
 @dataclass
 class ConfigWithList:
     list1: List[int] = field(default_factory=lambda: [1, 2, 3])

tests/structured_conf/test_structured_config.py

@@ -49,6 +49,11 @@ class EnumConfigAssignments:
     illegal = ["foo", True, False, 4, 1.0]
 
 
+class LiteralConfigAssignments:
+    legal = ["foo", "bar", True, b"baz", 5, Color.GREEN]
+    illegal = ["fuh", False, 4, 1.0, b"feh", Color.RED]
+
+
 class IntegersConfigAssignments:
     legal = [("10", 10), ("-10", -10), 100, 0, 1, 1]
     illegal = ["foo", 1.0, float("inf"), float("nan"), Color.BLUE]
@@ -259,12 +264,14 @@ def validate(cfg: DictConfig) -> None:
             ("FloatConfig", FloatConfigAssignments, {}),
             ("StringConfig", StringConfigAssignments, {}),
             ("EnumConfig", EnumConfigAssignments, {}),
+            ("LiteralConfig", LiteralConfigAssignments, {}),
             # Use instance to build config
             ("BoolConfig", BoolConfigAssignments, {"with_default": False}),
             ("IntegersConfig", IntegersConfigAssignments, {"with_default": 42}),
             ("FloatConfig", FloatConfigAssignments, {"with_default": 42.0}),
             ("StringConfig", StringConfigAssignments, {"with_default": "fooooooo"}),
             ("EnumConfig", EnumConfigAssignments, {"with_default": Color.BLUE}),
+            ("LiteralConfig", LiteralConfigAssignments, {"with_default": "foo"}),
             ("AnyTypeConfig", AnyTypeConfigAssignments, {}),
         ],
     )

tests/test_matrix.py

@@ -1,5 +1,6 @@
 import copy
 import re
+import sys
 from typing import Any, Optional
 
 from pytest import mark, raises, warns
@@ -11,6 +12,7 @@
     FloatNode,
     IntegerNode,
     ListConfig,
+    LiteralNode,
     OmegaConf,
     StringNode,
     ValidationError,
@@ -19,6 +21,11 @@
 from omegaconf._utils import _is_optional
 from tests import Color, Group
 
+if sys.version_info >= (3, 8):
+    from typing import Literal
+else:
+    from typing_extensions import Literal
+
 SKIP = object()
 
 
@@ -68,6 +75,16 @@ def verify(
             ),
             [Color.RED],
         ),
+        # LiteralNode
+        (
+            lambda value, is_optional, key=None: LiteralNode(
+                literal_type=Literal["foo", 5, b"bar", True, Color.GREEN],
+                value=value,
+                is_optional=is_optional,
+                key=key,
+            ),
+            ["foo", 5, b"bar", True, Color.GREEN],
+        ),
         # DictConfig
         (
             lambda value, is_optional, key=None: DictConfig(
@@ -96,6 +113,7 @@ def verify(
         "IntegerNode",
         "StringNode",
         "EnumNode",
+        "LiteralNode",
         "DictConfig",
         "ListConfig",
         "dataclass",