feat(typing): make types more precise for many common Values

ibis/expr/types/generic.py

@@ -1484,7 +1484,7 @@ def __polars_result__(self, df: pl.DataFrame) -> Any:
 
         return PolarsData.convert_scalar(df, self.type())
 
-    def as_scalar(self) -> Scalar:
+    def as_scalar(self) -> Self:
         """Tell ibis to treat this expression as a single scalar value.
 
         If the expression is a literal, it will be returned as is.
@@ -2481,7 +2481,7 @@ def first(
         where: ir.BooleanValue | None = None,
         order_by: Any = None,
         include_null: bool = False,
-    ) -> Value:
+    ) -> Scalar:
         """Return the first value of a column.
 
         Parameters
@@ -2535,7 +2535,7 @@ def last(
         where: ir.BooleanValue | None = None,
         order_by: Any = None,
         include_null: bool = False,
-    ) -> Value:
+    ) -> Scalar:
         """Return the last value of a column.
 
         Parameters
@@ -2647,7 +2647,7 @@ def dense_rank(self) -> ir.IntegerColumn:
         """
         return ibis.dense_rank().over(order_by=self)
 
-    def percent_rank(self) -> Column:
+    def percent_rank(self) -> ir.FloatingColumn:
         """Return the relative rank of the values in the column.
 
         Examples
@@ -2671,7 +2671,7 @@ def percent_rank(self) -> Column:
         """
         return ibis.percent_rank().over(order_by=self)
 
-    def cume_dist(self) -> Column:
+    def cume_dist(self) -> ir.FloatingColumn:
         """Return the cumulative distribution over a window.
 
         Examples
@@ -3015,7 +3015,7 @@ class NullColumn(Column, NullValue):
 
 @public
 @deferrable
-def null(type: dt.DataType | str | None = None, /) -> Value:
+def null(type: dt.DataType | str | None = None, /) -> NullScalar:
     """Create a NULL scalar.
 
     `NULL`s with an unspecified type are castable and comparable to values,

ibis/expr/types/logical.py

@@ -11,6 +11,8 @@
 from ibis.expr.types.numeric import NumericColumn, NumericScalar, NumericValue
 
 if TYPE_CHECKING:
+    from typing_extensions import Self
+
     import ibis.expr.types as ir
 
 
@@ -53,7 +55,7 @@ def ifelse(self, true_expr: ir.Value, false_expr: ir.Value, /) -> ir.Value:
         # must be used.
         return ops.IfElse(self, true_expr, false_expr).to_expr()
 
-    def __and__(self, other: BooleanValue) -> BooleanValue:
+    def __and__(self, other: bool | BooleanValue | ibis.Deferred) -> BooleanValue:
         """Construct a binary AND conditional expression with `self` and `other`.
 
         Parameters
@@ -101,7 +103,7 @@ def __and__(self, other: BooleanValue) -> BooleanValue:
 
     __rand__ = __and__
 
-    def __or__(self, other: BooleanValue) -> BooleanValue:
+    def __or__(self, other: bool | BooleanValue | ibis.Deferred) -> BooleanValue:
         """Construct a binary OR conditional expression with `self` and `other`.
 
         Parameters
@@ -137,7 +139,7 @@ def __or__(self, other: BooleanValue) -> BooleanValue:
 
     __ror__ = __or__
 
-    def __xor__(self, other: BooleanValue) -> BooleanValue:
+    def __xor__(self, other: bool | BooleanValue | ibis.Deferred) -> BooleanValue:
         """Construct a binary XOR conditional expression with `self` and `other`.
 
         Parameters
@@ -198,7 +200,7 @@ def __xor__(self, other: BooleanValue) -> BooleanValue:
 
     __rxor__ = __xor__
 
-    def __invert__(self) -> BooleanValue:
+    def __invert__(self) -> Self:
         """Construct a unary NOT conditional expression with `self`.
 
         Parameters
@@ -230,7 +232,7 @@ def __invert__(self) -> BooleanValue:
         """
         return ops.Not(self).to_expr()
 
-    def negate(self) -> BooleanValue:
+    def negate(self) -> Self:
         """DEPRECATED."""
         util.warn_deprecated(
             "`-bool_val`/`bool_val.negate()`",
@@ -247,7 +249,9 @@ class BooleanScalar(NumericScalar, BooleanValue):
 
 @public
 class BooleanColumn(NumericColumn, BooleanValue):
-    def any(self, *, where: BooleanValue | None = None) -> BooleanValue:
+    def any(
+        self, *, where: bool | BooleanValue | ibis.Deferred | None = None
+    ) -> BooleanScalar:
         """Return whether at least one element is `True`.
 
         If the expression does not reference any foreign tables, the result
@@ -339,7 +343,9 @@ def resolve_exists_subquery(outer):
 
         return op.to_expr()
 
-    def notany(self, *, where: BooleanValue | None = None) -> BooleanValue:
+    def notany(
+        self, *, where: bool | BooleanValue | ibis.Deferred | None = None
+    ) -> BooleanScalar:
         """Return whether no elements are `True`.
 
         Parameters
@@ -373,7 +379,9 @@ def notany(self, *, where: BooleanValue | None = None) -> BooleanValue:
         """
         return ~self.any(where=where)
 
-    def all(self, *, where: BooleanValue | None = None) -> BooleanScalar:
+    def all(
+        self, *, where: bool | BooleanValue | ibis.Deferred | None = None
+    ) -> BooleanScalar:
         """Return whether all elements are `True`.
 
         Parameters
@@ -410,7 +418,9 @@ def all(self, *, where: BooleanValue | None = None) -> BooleanScalar:
         """
         return ops.All(self, where=self._bind_to_parent_table(where)).to_expr()
 
-    def notall(self, *, where: BooleanValue | None = None) -> BooleanScalar:
+    def notall(
+        self, *, where: bool | BooleanValue | ibis.Deferred | None = None
+    ) -> BooleanScalar:
         """Return whether not all elements are `True`.
 
         Parameters
@@ -447,7 +457,13 @@ def notall(self, *, where: BooleanValue | None = None) -> BooleanScalar:
         """
         return ~self.all(where=where)
 
-    def cumany(self, *, where=None, group_by=None, order_by=None) -> BooleanColumn:
+    def cumany(
+        self,
+        *,
+        where: bool | BooleanValue | ibis.Deferred | None = None,
+        group_by=None,
+        order_by=None,
+    ) -> BooleanColumn:
         """Accumulate the `any` aggregate.
 
         Returns
@@ -487,7 +503,13 @@ def cumany(self, *, where=None, group_by=None, order_by=None) -> BooleanColumn:
             ibis.cumulative_window(group_by=group_by, order_by=order_by)
         )
 
-    def cumall(self, *, where=None, group_by=None, order_by=None) -> BooleanColumn:
+    def cumall(
+        self,
+        *,
+        where: bool | BooleanValue | ibis.Deferred | None = None,
+        group_by=None,
+        order_by=None,
+    ) -> BooleanColumn:
         """Accumulate the `all` aggregate.
 
         Returns