rule-engine 5.0.0__py3-none-any.whl

rule_engine/ast/expression/control.py

@@ -0,0 +1,256 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+#
+#  rule_engine/ast/expression/control.py
+#
+#  Redistribution and use in source and binary forms, with or without
+#  modification, are permitted provided that the following conditions are
+#  met:
+#
+#  * Redistributions of source code must retain the above copyright
+#    notice, this list of conditions and the following disclaimer.
+#  * Redistributions in binary form must reproduce the above
+#    copyright notice, this list of conditions and the following disclaimer
+#    in the documentation and/or other materials provided with the
+#    distribution.
+#  * Neither the name of the project nor the names of its
+#    contributors may be used to endorse or promote products derived from
+#    this software without specific prior written permission.
+#
+#  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+#  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+#  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+#  A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+#  OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+#  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+#  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+#  DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+#  THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+#  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+#  OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+#
+
+import collections
+import datetime
+import functools
+import operator
+from typing import TYPE_CHECKING, Any, Callable
+
+from ... import errors
+from ...types import DataType, is_numeric
+from ...types import _DataTypeDef
+
+from ..base import (
+        Assignment,
+        ExpressionBase,
+        LiteralExpressionBase,
+        _assert_not_nullable,
+        _is_reduced,
+        _propagate_nullable,
+        _resolve_type,
+)
+from ..literal import BooleanExpression, FloatExpression, TimedeltaExpression
+
+if TYPE_CHECKING:
+    from ...engine.context import Context
+
+class ComprehensionExpression(ExpressionBase):
+    result_type: _DataTypeDef = DataType.ARRAY
+    def __init__(
+            self,
+            context: 'Context',
+            result: ExpressionBase,
+            variable: str,
+            iterable: ExpressionBase,
+            condition: ExpressionBase | None = None
+    ) -> None:
+        self.context = context
+        self.result = result
+        self.variable = variable
+        self.iterable = iterable
+        self.condition = condition
+        self.result_type = DataType.ARRAY(self.result.result_type)
+
+    @classmethod
+    def build(  # type: ignore[override]
+            cls,
+            context: 'Context',
+            result: ExpressionBase,
+            variable: str,
+            iterable: ExpressionBase,
+            condition: ExpressionBase | None = None
+    ) -> ExpressionBase:
+        iterable_built = iterable.build()
+        assert isinstance(iterable_built, ExpressionBase)
+        if iterable_built.result_type is not DataType.UNDEFINED and not iterable_built.result_type.is_iterable:
+            raise errors.EvaluationError('data type mismatch (comprehension requires an iterable)')
+        resolved_iterable_type = _resolve_type(iterable_built.result_type, context)
+        assignment = Assignment(variable, value_type=getattr(resolved_iterable_type, 'iterable_type', DataType.UNDEFINED))
+        with context.assignments(assignment):
+            if condition is not None:
+                condition_built = condition.build()
+                assert isinstance(condition_built, ExpressionBase)
+                condition = condition_built
+            result_built = result.build()
+            assert isinstance(result_built, ExpressionBase)
+            result = result_built
+        reduced = cls(context, result, variable, iterable_built, condition=condition).reduce()
+        assert isinstance(reduced, ExpressionBase)
+        return reduced
+
+    def __repr__(self) -> str:
+        return "<{0} iterable={1!r} result={2!r} condition={3!r} >".format(self.__class__.__name__, self.iterable, self.result, self.condition)
+
+    def evaluate(self, thing: Any) -> Any:
+        output_array: 'collections.deque[Any]' = collections.deque()
+        input_iterable = self.iterable.evaluate(thing)
+        if not DataType.from_value(input_iterable).is_iterable:
+            raise errors.EvaluationError('data type mismatch (comprehension requires an iterable)')
+        for value in input_iterable:
+            assignment = Assignment(self.variable, value=value)
+            with self.context.assignments(assignment):
+                if self.condition is None or self.condition.evaluate(thing):
+                    output_array.append(self.result.evaluate(thing))
+        return tuple(output_array)
+
+    def to_graphviz(self, digraph: Any, *args: Any, **kwargs: Any) -> None:
+        digraph.node(str(id(self)), "{}\nvariable={!r}".format(self.__class__.__name__, self.variable))
+        self.result.to_graphviz(digraph, *args, **kwargs)
+        digraph.edge(str(id(self)), str(id(self.result)), label='result')
+        self.iterable.to_graphviz(digraph, *args, **kwargs)
+        digraph.edge(str(id(self)), str(id(self.iterable)), label='iterable')
+        if self.condition is not None:
+            self.condition.to_graphviz(digraph, *args, **kwargs)
+            digraph.edge(str(id(self)), str(id(self.condition)), label='condition')
+
+class TernaryExpression(ExpressionBase):
+    """
+    A class for representing ternary expressions from the grammar text. These involve evaluating :py:attr:`.condition`
+    before evaluating either :py:attr:`.case_true` or :py:attr:`.case_false` based on the results.
+    """
+    def __init__(self, context: 'Context', condition: ExpressionBase, case_true: ExpressionBase, case_false: ExpressionBase) -> None:
+        """
+        :param context: The context to use for evaluating the expression.
+        :type context: :py:class:`~rule_engine.engine.Context`
+        :param condition: The condition expression whose evaluation determines whether the *case_true* or *case_false*
+                expression is evaluated.
+        :param case_true: The expression that's evaluated when *condition* is True.
+        :param case_false:The expression that's evaluated when *condition* is False.
+        """
+        self.context = context
+        self.condition = condition
+        self.case_true = case_true
+        self.case_false = case_false
+        true_type = DataType.NULLABLE.unwrap(self.case_true.result_type)
+        false_type = DataType.NULLABLE.unwrap(self.case_false.result_type)
+        if true_type == false_type:
+            self.result_type = true_type
+        elif DataType.is_type(true_type, DataType.ARRAY) and DataType.is_type(false_type, DataType.ARRAY):
+            self.result_type = DataType.ARRAY
+        # todo: the other compound types should be checked here as well.
+        self.result_type = _propagate_nullable(self.result_type, self.case_true.result_type, self.case_false.result_type)
+
+    @classmethod
+    def build(cls, context: 'Context', condition: ExpressionBase, case_true: ExpressionBase, case_false: ExpressionBase) -> ExpressionBase:  # type: ignore[override]
+        condition_built = condition.build()
+        assert isinstance(condition_built, ExpressionBase)
+        case_true_built = case_true.build()
+        assert isinstance(case_true_built, ExpressionBase)
+        case_false_built = case_false.build()
+        assert isinstance(case_false_built, ExpressionBase)
+        reduced = cls(context, condition_built, case_true_built, case_false_built).reduce()
+        assert isinstance(reduced, ExpressionBase)
+        return reduced
+
+    def evaluate(self, thing: Any) -> Any:
+        case = (self.case_true if self.condition.evaluate(thing) else self.case_false)
+        return case.evaluate(thing)
+
+    def reduce(self) -> ExpressionBase:
+        if not _is_reduced(self.condition):
+            return self
+        assert isinstance(self.condition, LiteralExpressionBase)
+        reduced_condition = bool(self.condition.value)
+        reduced = self.case_true.reduce() if reduced_condition else self.case_false.reduce()
+        assert isinstance(reduced, ExpressionBase)
+        return reduced
+
+    def to_graphviz(self, digraph: Any, *args: Any, **kwargs: Any) -> None:
+        super(TernaryExpression, self).to_graphviz(digraph, *args, **kwargs)
+        self.condition.to_graphviz(digraph, *args, **kwargs)
+        self.case_true.to_graphviz(digraph, *args, **kwargs)
+        self.case_false.to_graphviz(digraph, *args, **kwargs)
+        digraph.edge(str(id(self)), str(id(self.condition)), label='condition')
+        digraph.edge(str(id(self)), str(id(self.case_true)), label='true case')
+        digraph.edge(str(id(self)), str(id(self.case_false)), label='false case')
+
+class UnaryExpression(ExpressionBase):
+    """
+    A class for representing unary expressions from the grammar text. These involve a single operator on the left side.
+    """
+    def __init__(self, context: 'Context', type_: str, right: ExpressionBase) -> None:
+        """
+        :param context: The context to use for evaluating the expression.
+        :type context: :py:class:`~rule_engine.engine.Context`
+        :param str type_: The grammar type of operator to the left of the expression.
+        :param right: The expression to the right of the operator.
+        :type right: :py:class:`~.ExpressionBase`
+        """
+        self.context = context
+        type_ = type_.lower()
+        self.type = type_
+        if type_ == 'not':
+            self.result_type = DataType.BOOLEAN
+        elif type_ == 'uminus':
+            _assert_not_nullable(right.result_type, role='unary minus operand')
+            self.result_type = right.result_type
+        else:
+            raise ValueError('unknown unary expression type')
+        self._evaluator = getattr(self, '_op_' + type_)
+        self.right = right
+
+    @classmethod
+    def build(cls, context: 'Context', type_: str, right: ExpressionBase) -> ExpressionBase:  # type: ignore[override]
+        right_built = right.build()
+        assert isinstance(right_built, ExpressionBase)
+        reduced = cls(context, type_, right_built).reduce()
+        assert isinstance(reduced, ExpressionBase)
+        return reduced
+
+    def __repr__(self) -> str:
+        return "<{} type={!r} >".format(self.__class__.__name__, self.type)
+
+    def evaluate(self, thing: Any) -> Any:
+        return self._evaluator(thing)
+
+    def __op(self, op: Callable[[Any], Any], thing: Any) -> Any:
+        return op(self.right.evaluate(thing))
+
+    _op_not = functools.partialmethod(__op, operator.not_)
+
+    def __op_arithmetic(self, op: Callable[[Any], Any], thing: Any) -> Any:
+        right = self.right.evaluate(thing)
+        if not is_numeric(right) and not isinstance(right, datetime.timedelta):
+            raise errors.EvaluationError('data type mismatch (not a numeric or timedelta value)')
+        return op(right)
+
+    _op_uminus = functools.partialmethod(__op_arithmetic, operator.neg)
+
+    def reduce(self) -> ExpressionBase:
+        type_ = self.type.lower()
+        if not _is_reduced(self.right):
+            return self
+        if type_ == 'not':
+            return BooleanExpression(self.context, self.evaluate(None))
+        elif type_ == 'uminus':
+            if isinstance(self.right, FloatExpression):
+                return FloatExpression(self.context, self.evaluate(None))
+            elif isinstance(self.right, TimedeltaExpression):
+                return TimedeltaExpression(self.context, self.evaluate(None))
+            raise errors.EvaluationError('data type mismatch (not a float or timedelta expression)')
+        raise errors.EngineError('unsupported unary expression type')
+
+    def to_graphviz(self, digraph: Any, *args: Any, **kwargs: Any) -> None:
+        digraph.node(str(id(self)), "{}\ntype={!r}".format(self.__class__.__name__, self.type.lower()))
+        self.right.to_graphviz(digraph, *args, **kwargs)
+        digraph.edge(str(id(self)), str(id(self.right)))

rule_engine/ast/expression/resolution.py

@@ -0,0 +1,220 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+#
+#  rule_engine/ast/expression/resolution.py
+#
+#  Redistribution and use in source and binary forms, with or without
+#  modification, are permitted provided that the following conditions are
+#  met:
+#
+#  * Redistributions of source code must retain the above copyright
+#    notice, this list of conditions and the following disclaimer.
+#  * Redistributions in binary form must reproduce the above
+#    copyright notice, this list of conditions and the following disclaimer
+#    in the documentation and/or other materials provided with the
+#    distribution.
+#  * Neither the name of the project nor the names of its
+#    contributors may be used to endorse or promote products derived from
+#    this software without specific prior written permission.
+#
+#  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+#  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+#  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+#  A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+#  OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+#  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+#  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+#  DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+#  THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+#  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+#  OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+#
+
+from typing import TYPE_CHECKING, Any, Iterable
+
+from ... import errors
+from ...types import DataType
+from ...types import _CollectionDataTypeDef, _DataTypeDef, _FunctionDataTypeDef, _MappingDataTypeDef
+
+from ..base import ExpressionBase, LiteralExpressionBase, _is_reduced
+
+if TYPE_CHECKING:
+    from ...engine.context import Context
+
+class SymbolExpression(ExpressionBase):
+    """
+    A class representing a symbol name to be resolved at evaluation time with the help of a
+    :py:class:`~rule_engine.engine.Context` object.
+    """
+    __slots__ = ('name', 'result_type', 'scope')
+    def __init__(self, context: 'Context', name: str, scope: str | None = None) -> None:
+        """
+        :param context: The context to use for evaluating the expression.
+        :type context: :py:class:`~rule_engine.engine.Context`
+        :param str name: The name of the symbol. This will be resolved with a given context object on the specified
+                *thing*.
+        :param str scope: The optional scope to use while resolving the symbol.
+        """
+        context.symbols.add(name)
+        self.context = context
+        self.name = name
+        type_hint = context.resolve_type(name, scope=scope)
+        if type_hint is not None:
+            self.result_type = type_hint
+        self.scope = scope
+
+    def __repr__(self) -> str:
+        return "<{0} name={1!r} >".format(self.__class__.__name__, self.name)
+
+    def evaluate(self, thing: Any) -> Any:
+        try:
+            value = self.context.resolve(thing, self.name, scope=self.scope)
+        except errors.SymbolResolutionError:
+            default_value = self.context.default_value
+            if default_value is errors.UNDEFINED:
+                raise
+            value = default_value
+        value = self._new_value(value, verify_type=False)
+
+        # if the expected result type is undefined, return the value
+        if self.result_type == DataType.UNDEFINED:
+            return value
+
+        # NULLABLE(T) is T-or-None at runtime; None is always valid, and any other value is checked against the
+        # unwrapped inner type
+        effective_type: _DataTypeDef = self.result_type
+        if DataType.is_type(effective_type, DataType.NULLABLE):
+            if value is None:
+                return value
+            effective_type = effective_type.inner_type
+
+        # OBJECT values are opaque to DataType.from_value; trust the schema annotation and delegate attribute-level
+        # type checking to GetAttributeExpression
+        if DataType.is_type(effective_type, DataType.OBJECT):
+            return value
+
+        # use DataType.from_value to raise a TypeError if value is not of a
+        # compatible data type
+        value_type = DataType.from_value(value)
+
+        # if the type is the expected result type, return the value
+        if DataType.is_compatible(value_type, effective_type):
+            if effective_type.is_scalar:
+                return value
+            assert isinstance(effective_type, (_CollectionDataTypeDef, _MappingDataTypeDef))
+            assert isinstance(value_type, (_CollectionDataTypeDef, _MappingDataTypeDef))
+            if effective_type.value_type == DataType.UNDEFINED:
+                return value
+            if value_type.value_type == DataType.UNDEFINED:
+                return value
+            if effective_type.value_type != DataType.NULL and not effective_type.value_type_nullable and any(v is None for v in value):
+                raise errors.SymbolTypeError(self.name, is_value=value, is_type=value_type, expected_type=self.result_type)
+            if DataType.is_compatible(effective_type.value_type, value_type.value_type):
+                return value
+
+        # if the type is null, return the value (treat null as a special case)
+        if value_type == DataType.NULL:
+            return value
+
+        raise errors.SymbolTypeError(self.name, is_value=value, is_type=value_type, expected_type=self.result_type)
+
+    def to_graphviz(self, digraph: Any, *args: Any, **kwargs: Any) -> None:
+        digraph.node(str(id(self)), "{}\nname={!r}".format(self.__class__.__name__, self.name))
+
+class FunctionCallExpression(ExpressionBase):
+    __slots__ = ('function', 'arguments',)
+    arguments: tuple[ExpressionBase, ...]
+    def __init__(self, context: 'Context', function: ExpressionBase, arguments: Iterable[ExpressionBase]) -> None:
+        self.context = context
+        self.function = function
+        argument_tuple: tuple[ExpressionBase, ...] = tuple(arguments)
+        if self.function.result_type != DataType.UNDEFINED:
+            function_type = self.function.result_type
+            self._validate_function(function_type, argument_tuple)
+            assert isinstance(function_type, _FunctionDataTypeDef)
+            self.result_type = function_type.return_type
+        self.arguments = argument_tuple
+
+    @classmethod
+    def build(cls, context: 'Context', function: ExpressionBase, arguments: Iterable[ExpressionBase]) -> ExpressionBase:  # type: ignore[override]
+        function_built = function.build()
+        assert isinstance(function_built, ExpressionBase)
+        built_args: list[ExpressionBase] = []
+        for argument in arguments:
+            argument_built = argument.build()
+            assert isinstance(argument_built, ExpressionBase)
+            built_args.append(argument_built)
+        reduced = cls(context, function_built, tuple(built_args)).reduce()
+        assert isinstance(reduced, ExpressionBase)
+        return reduced
+
+    def reduce(self) -> ExpressionBase:
+        if not _is_reduced(self.function, *self.arguments):
+            return self
+        return LiteralExpressionBase.from_value(self.context, self.evaluate(None))
+
+    def evaluate(self, thing: Any) -> Any:
+        function = self.function.evaluate(thing)
+        if not callable(function):
+            raise errors.EvaluationError('data type mismatch (not a callable value)')
+        arguments = tuple(argument.evaluate(thing) for argument in self.arguments)
+        function_name: str | None = '<unknown>'
+        if self.function.result_type != DataType.UNDEFINED:
+            function_type = self.function.result_type
+            assert isinstance(function_type, _FunctionDataTypeDef)
+            function_name = function_type.value_name
+            self._validate_function(function_type, arguments)
+        elif hasattr(function, '__name__'):
+            function_name = function.__name__ + '?'
+        try:
+            result = function(*arguments)
+        except errors.FunctionCallError as error:
+            error.function_name = function_name
+            raise error
+        except Exception as error:
+            raise errors.FunctionCallError('function call failed', error=error, function_name=function_name) from None
+        result = self._new_value(result)
+        if not DataType.is_compatible(DataType.from_value(result), self.result_type):
+            raise errors.FunctionCallError('function call failed (data type mismatch on returned value)', function_name=function_name)
+        return result
+
+    def _validate_function(self, function_type: _DataTypeDef, arguments: 'tuple[Any, ...]') -> None:
+        if not isinstance(function_type, _FunctionDataTypeDef):
+            raise errors.EvaluationError('data type mismatch (not a callable value)')
+        if function_type.minimum_arguments is not DataType.UNDEFINED:
+            assert isinstance(function_type.minimum_arguments, int)
+            if len(arguments) < function_type.minimum_arguments:
+                raise errors.FunctionCallError(
+                        "expected at least {} positional arguments".format(function_type.minimum_arguments),
+                        function_name=function_type.value_name
+                )
+        if function_type.argument_types is not DataType.UNDEFINED:
+            assert isinstance(function_type.argument_types, tuple)
+            if len(arguments) > len(function_type.argument_types):
+                raise errors.FunctionCallError(
+                        "expected at most {} positional arguments".format(len(function_type.argument_types)),
+                        function_name=function_type.value_name
+                )
+            for pos, (arg1, arg2_type) in enumerate(zip(arguments, function_type.argument_types), 1):
+                if isinstance(arg1, ExpressionBase):
+                    arg1_type = arg1.result_type
+                else:
+                    arg1_type = DataType.from_value(arg1)
+                if not DataType.is_compatible(arg1_type, arg2_type):
+                    raise errors.FunctionCallError(
+                            "data type mismatch (argument #{})".format(pos),
+                            function_name=function_type.value_name
+                    )
+                if DataType.is_type(arg1_type, DataType.NULLABLE) and not DataType.is_type(arg2_type, DataType.NULLABLE) and arg2_type != DataType.UNDEFINED:
+                    raise errors.FunctionCallError(
+                            "data type mismatch (argument #{} is nullable; discharge with '??' or use '&.' / '&[' for safe navigation)".format(pos),
+                            function_name=function_type.value_name
+                    )
+
+    def to_graphviz(self, digraph: Any, *args: Any, **kwargs: Any) -> None:
+        super(FunctionCallExpression, self).to_graphviz(digraph, *args, **kwargs)
+        self.function.to_graphviz(digraph, *args, **kwargs)
+        digraph.edge(str(id(self)), str(id(self.function)), label='function')
+        for idx, argument in enumerate(self.arguments, 1):
+            argument.to_graphviz(digraph, *args, **kwargs)
+            digraph.edge(str(id(self)), str(id(argument)), label="argument #{}".format(idx))

rule_engine/ast/literal.py

@@ -0,0 +1,183 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+#
+#  rule_engine/ast/literal.py
+#
+#  Redistribution and use in source and binary forms, with or without
+#  modification, are permitted provided that the following conditions are
+#  met:
+#
+#  * Redistributions of source code must retain the above copyright
+#    notice, this list of conditions and the following disclaimer.
+#  * Redistributions in binary form must reproduce the above
+#    copyright notice, this list of conditions and the following disclaimer
+#    in the documentation and/or other materials provided with the
+#    distribution.
+#  * Neither the name of the project nor the names of its
+#    contributors may be used to endorse or promote products derived from
+#    this software without specific prior written permission.
+#
+#  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+#  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+#  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+#  A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+#  OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+#  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+#  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+#  DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+#  THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+#  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+#  OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+#
+
+import collections
+from typing import TYPE_CHECKING, Any, Iterable
+
+from .. import errors
+from ..parser.utilities import parse_datetime, parse_float, parse_timedelta
+from ..types import DataType, coerce_value
+from ..types import _DataTypeDef
+
+from .base import ExpressionBase, LiteralExpressionBase, _is_reduced, _iterable_member_value_type
+
+if TYPE_CHECKING:
+    from ..engine.context import Context
+
+################################################################################
+# Literal Expressions
+################################################################################
+class _CollectionMixin(object):
+    # these attributes are provided by the LiteralExpressionBase half of the subclasses
+    result_type: _DataTypeDef
+    value: Any
+    def evaluate(self, thing: Any) -> Any:
+        return self.result_type.python_type(member.evaluate(thing) for member in self.value)
+
+    @property
+    def is_reduced(self) -> bool:  # type: ignore[override]
+        return _is_reduced(*self.value)
+
+    def to_graphviz(self, digraph: Any, *args: Any, **kwargs: Any) -> None:
+        super(_CollectionMixin, self).to_graphviz(digraph, *args, **kwargs)  # type: ignore[misc]
+        for member in self.value:
+            member.to_graphviz(digraph, *args, **kwargs)
+            digraph.edge(str(id(self)), str(id(member)))
+
+class ArrayExpression(_CollectionMixin, LiteralExpressionBase):  # type: ignore[override]
+    """Literal array expressions containing 0 or more sub-expressions."""
+    result_type: _DataTypeDef = DataType.ARRAY
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        super(ArrayExpression, self).__init__(*args, **kwargs)
+        self.result_type = DataType.ARRAY(value_type=_iterable_member_value_type(self.value))
+
+    @classmethod
+    def build(cls, context: 'Context', value: Iterable[ExpressionBase]) -> 'ArrayExpression':  # type: ignore[override]
+        return cls(context, [member.build() for member in value])
+
+class BooleanExpression(LiteralExpressionBase):
+    """Literal boolean expressions representing True or False."""
+    result_type: _DataTypeDef = DataType.BOOLEAN
+
+class BytesExpression(LiteralExpressionBase):
+    """
+    Literal bytes expressions representing a binary string. This expression type always evaluates to true when not empty.
+    """
+    result_type: _DataTypeDef = DataType.BYTES
+
+class DatetimeExpression(LiteralExpressionBase):
+    """
+    Literal datetime expressions representing a specific point in time. This expression type always evaluates to true.
+    """
+    result_type: _DataTypeDef = DataType.DATETIME
+    @classmethod
+    def from_string(cls, context: 'Context', string: str) -> 'DatetimeExpression':
+        dt = parse_datetime(string, default_timezone=context.default_timezone)
+        return cls(context, dt)
+
+class TimedeltaExpression(LiteralExpressionBase):
+    """
+    Literal timedelta expressions representing an offset from a specific point in time.
+
+    .. versionadded:: 3.5.0
+    """
+    result_type: _DataTypeDef = DataType.TIMEDELTA
+    @classmethod
+    def from_string(cls, context: 'Context', string: str) -> 'TimedeltaExpression':
+        return cls(context, parse_timedelta(string))
+
+class FloatExpression(LiteralExpressionBase):
+    """Literal float expressions representing numerical values."""
+    result_type: _DataTypeDef = DataType.FLOAT
+    def __init__(self, context: 'Context', value: Any, **kwargs: Any) -> None:
+        value = coerce_value(value)
+        super(FloatExpression, self).__init__(context, value, **kwargs)
+
+    @classmethod
+    def from_string(cls, context: 'Context', string: str) -> 'FloatExpression':
+        return cls(context, parse_float(string))
+
+class FunctionExpression(LiteralExpressionBase):
+    """Literal mapping expression representing a function."""
+    # there's no syntax for defining functions, but this is required by the parser when a method is referred to on a
+    # literal value, e.g. `b"41".decode('utf-8')`
+    result_type: _DataTypeDef = DataType.FUNCTION
+
+class MappingExpression(LiteralExpressionBase):
+    """Literal mapping expression representing a set of associations between keys and values."""
+    result_type: _DataTypeDef = DataType.MAPPING
+    def __init__(self, context: 'Context', value: Any, **kwargs: Any) -> None:
+        if isinstance(value, dict):
+            value = tuple(value.items())
+        super(MappingExpression, self).__init__(context, value, **kwargs)
+        self.result_type = DataType.MAPPING(
+                key_type=_iterable_member_value_type(key for key, _ in self.value),
+                value_type=_iterable_member_value_type(value for _, value in self.value)
+        )
+
+    @classmethod
+    def build(cls, context: 'Context', value: Any) -> 'MappingExpression':  # type: ignore[override]
+        value = collections.OrderedDict(value)
+        value = collections.OrderedDict((k.build(), v.build()) for k, v in value.items())
+        return cls(context, value)
+
+    def evaluate(self, thing: Any) -> Any:
+        mapping: 'collections.OrderedDict[Any, Any]' = collections.OrderedDict()
+        for key, value in self.value:
+            key = key.evaluate(thing)
+            key_type = DataType.from_value(key)
+            if key_type.is_compound and not DataType.is_type(key_type, DataType.ARRAY):
+                raise errors.EngineError("the {} data type may not be used for mapping keys".format(key_type.name))
+            mapping[key] = value
+        # defer value evaluation to avoid evaluating values of duplicate keys
+        for key, value in mapping.items():
+            mapping[key] = value.evaluate(thing)
+        return mapping
+
+    @property
+    def is_reduced(self) -> bool:  # type: ignore[override]
+        return all(_is_reduced(key, value) for key, value in self.value)
+
+class NullExpression(LiteralExpressionBase):
+    """Literal null expressions representing null values. This expression type always evaluates to false."""
+    result_type: _DataTypeDef = DataType.NULL
+    def __init__(self, context: 'Context', value: Any = None) -> None:
+        # all of the literal expressions take a value
+        if value is not None:
+            raise TypeError('value must be None')
+        super(NullExpression, self).__init__(context, value=None)
+
+class SetExpression(_CollectionMixin, LiteralExpressionBase):  # type: ignore[override]
+    """Literal set expressions containing 0 or more sub-expressions."""
+    result_type: _DataTypeDef = DataType.SET
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        super(SetExpression, self).__init__(*args, **kwargs)
+        self.result_type = DataType.SET(value_type=_iterable_member_value_type(self.value))
+
+    @classmethod
+    def build(cls, context: 'Context', value: Iterable[ExpressionBase]) -> 'SetExpression':  # type: ignore[override]
+        built = set(member.build() for member in value)
+        return cls(context, built)
+
+class StringExpression(LiteralExpressionBase):
+    """Literal string expressions representing an array of characters."""
+    result_type: _DataTypeDef = DataType.STRING