refactor: move _binop() util function to be near ir.Value, not ir.Expr

This function is only uses with Values, not general Expr,
so it should be co-located there.

This adds a runtime assert to verify we are using this correctly internally.

It also improves the docstring to not be misleading about ops.Binary,
and to give some more examples of the edge cases.

Author: NickCrews

ibis/expr/types/core.py

@@ -9,7 +9,6 @@
 
 import ibis
 import ibis.expr.operations as ops
-from ibis.common.annotations import ValidationError
 from ibis.common.exceptions import IbisError, TranslationError
 from ibis.common.grounds import Immutable
 from ibis.common.patterns import Coercible, CoercionError
@@ -944,38 +943,3 @@ def as_scalar(self) -> ir.Scalar:
         raise NotImplementedError(
             f"{type(self)} expressions cannot be converted into scalars"
         )
-
-
-def _binop(op_class: type[ops.Binary], left: ir.Value, right: ir.Value) -> ir.Value:
-    """Try to construct a binary operation.
-
-    Parameters
-    ----------
-    op_class
-        The `ops.Binary` subclass for the operation
-    left
-        Left operand
-    right
-        Right operand
-
-    Returns
-    -------
-    ir.Value
-        A value expression
-
-    Examples
-    --------
-    >>> import ibis
-    >>> import ibis.expr.operations as ops
-    >>> expr = _binop(ops.TimeAdd, ibis.time("01:00"), ibis.interval(hours=1))
-    >>> expr
-    TimeAdd(datetime.time(1, 0), 1h): datetime.time(1, 0) + 1 h
-    >>> _binop(ops.TimeAdd, 1, ibis.interval(hours=1))
-    TimeAdd(datetime.time(0, 0, 1), 1h): datetime.time(0, 0, 1) + 1 h
-    """
-    try:
-        node = op_class(left, right)
-    except (ValidationError, NotImplementedError):
-        return NotImplemented
-    else:
-        return node.to_expr()

ibis/expr/types/generic.py

@@ -10,10 +10,11 @@
 import ibis.expr.builders as bl
 import ibis.expr.datatypes as dt
 import ibis.expr.operations as ops
+from ibis.common.annotations import ValidationError
 from ibis.common.deferred import Deferred, _, deferrable
 from ibis.common.grounds import Singleton
 from ibis.expr.rewrites import rewrite_window_input
-from ibis.expr.types.core import Expr, _binop
+from ibis.expr.types.core import Expr
 from ibis.expr.types.rich import FixedTextJupyterMixin, to_rich
 from ibis.util import deprecated, experimental, promote_list
 
@@ -3119,6 +3120,57 @@ def _is_null_literal(value: Any) -> bool:
     )
 
 
+def _binop(op_class: type[ops.Value], left: Value | Any, right: Value | Any) -> Value:
+    """Try to construct a binary operation between two Values.
+
+    Parameters
+    ----------
+    op_class
+        An ops.Value that accepts two Value positional operands.
+        Not necessarily a ops.Binary subclass,
+        eg this works with ops.Repeat for string repetition.
+    left
+        Left operand. Can be a Value, or something coercible to a Value.
+    right
+        Right operand. Can be a Value, or something coercible to a Value.
+
+    Returns
+    -------
+    ir.Value
+        A value expression
+
+    Examples
+    --------
+    >>> import ibis
+    >>> import ibis.expr.operations as ops
+    >>> _binop(ops.TimeAdd, ibis.time("01:00"), ibis.interval(hours=1))
+    TimeAdd(datetime.time(1, 0), 1h): datetime.time(1, 0) + 1 h
+    >>> _binop(ops.TimeAdd, 1, ibis.interval(hours=1))
+    TimeAdd(datetime.time(0, 0, 1), 1h): datetime.time(0, 0, 1) + 1 h
+    >>> _binop(ops.Equals, 5, 2)
+    Equals(5, 2): 5 == 2
+
+    This raises if the operation is known to be invalid between the two operands:
+
+    >>> _binop(ops.Equals, ibis.literal("foo"), 2)  # quartodoc: +EXPECTED_FAILURE
+    Traceback (most recent call last):
+      ...
+    IbisTypeError: Arguments Literal(foo):string and Literal(2):int8 are not comparable
+
+    But returns NotImplemented if we aren't sure:
+
+    >>> _binop(ops.Equals, 5, ibis.table({"a": "int"}))
+    NotImplemented
+    """
+    assert issubclass(op_class, ops.Value)
+    try:
+        node = op_class(left, right)
+    except (ValidationError, NotImplementedError):
+        return NotImplemented
+    else:
+        return node.to_expr()
+
+
 public(
     ValueExpr=Value,
     ScalarExpr=Scalar,

ibis/expr/types/logical.py

@@ -7,7 +7,7 @@
 import ibis
 import ibis.expr.operations as ops
 from ibis import util
-from ibis.expr.types.core import _binop
+from ibis.expr.types.generic import _binop
 from ibis.expr.types.numeric import NumericColumn, NumericScalar, NumericValue
 
 if TYPE_CHECKING:

ibis/expr/types/numeric.py

@@ -8,8 +8,7 @@
 import ibis
 import ibis.expr.operations as ops
 from ibis.common.exceptions import IbisTypeError
-from ibis.expr.types.core import _binop
-from ibis.expr.types.generic import Column, Scalar, Value
+from ibis.expr.types.generic import Column, Scalar, Value, _binop
 
 if TYPE_CHECKING:
     import ibis.expr.types as ir

ibis/expr/types/strings.py

@@ -8,8 +8,7 @@
 
 import ibis.expr.operations as ops
 from ibis import util
-from ibis.expr.types.core import _binop
-from ibis.expr.types.generic import Column, Scalar, Value
+from ibis.expr.types.generic import Column, Scalar, Value, _binop
 
 if TYPE_CHECKING:
     from collections.abc import Iterable, Sequence

ibis/expr/types/temporal.py

@@ -11,8 +11,7 @@
 from ibis import util
 from ibis.common.annotations import annotated
 from ibis.common.temporal import IntervalUnit
-from ibis.expr.types.core import _binop
-from ibis.expr.types.generic import Column, Scalar, Value
+from ibis.expr.types.generic import Column, Scalar, Value, _binop
 from ibis.util import deprecated
 
 if TYPE_CHECKING: