docs(api): document more public expression APIs

Author: cpcloud

.pre-commit-config.yaml

@@ -26,7 +26,7 @@ repos:
     hooks:
       - id: ruff
         # exclude a file (if configured to do so), even if it's passed in explicitly
-        args: ["--force-exclude", "--fix"]
+        args: ["--force-exclude"]
   - repo: https://github.com/adrienverge/yamllint
     rev: v1.29.0
     hooks:

ibis/expr/operations/analytic.py

@@ -62,53 +62,11 @@ class RankBase(Analytic):
 
 @public
 class MinRank(RankBase):
-    """Compute position of first element within each equal-value group in sorted order.
-
-    Equivalent to SQL's `RANK()`.
-
-    Examples
-    --------
-    values   ranks
-    1        0
-    1        0
-    2        2
-    2        2
-    2        2
-    3        5
-
-    Returns
-    -------
-    Int64Column
-        The min rank
-    """
-
     arg = rlz.column(rlz.any)
 
 
 @public
 class DenseRank(RankBase):
-    """Position of first element within each group of equal values.
-
-    Values are returned in sorted order and duplicate values are ignored.
-
-    Equivalent to SQL's `DENSE_RANK()`.
-
-    Examples
-    --------
-    values   ranks
-    1        0
-    1        0
-    2        1
-    2        1
-    2        1
-    3        2
-
-    Returns
-    -------
-    IntegerColumn
-        The rank
-    """
-
     arg = rlz.column(rlz.any)
 
 
@@ -168,11 +126,6 @@ def output_dtype(self):
 
 @public
 class CumulativeMax(CumulativeOp):
-    """Cumulative max.
-
-    Requires an order window.
-    """
-
     arg = rlz.column(rlz.any)
     output_dtype = rlz.dtype_like("arg")
 

ibis/expr/types/core.py

@@ -64,6 +64,25 @@ def _repr(self) -> str:
         return fmt(self)
 
     def equals(self, other):
+        """Return whether this expression is _structurally_ equivalent to `other`.
+
+        If you want to produce an equality expression, use `==` syntax.
+
+        Parameters
+        ----------
+        other
+            Another expression
+
+        Examples
+        --------
+        >>> t1 = ibis.table(dict(a="int"), name="t")
+        >>> t2 = ibis.table(dict(a="int"), name="t")
+        >>> t1.equals(t2)
+        True
+        >>> v = ibis.table(dict(a="string"), name="v")
+        >>> t1.equals(v)
+        False
+        """
         if not isinstance(other, Expr):
             raise TypeError(
                 f"invalid equality comparison between Expr and {type(other)}"
@@ -76,9 +95,11 @@ def __bool__(self) -> bool:
     __nonzero__ = __bool__
 
     def has_name(self):
+        """Check whether this expression has an explicit name."""
         return isinstance(self._arg, ops.Named)
 
     def get_name(self):
+        """Return the name of this expression."""
         return self._arg.name
 
     def _repr_png_(self) -> bytes | None:
@@ -172,7 +193,7 @@ def pipe(self, f, *args: Any, **kwargs: Any) -> Expr:
         else:
             return f(self, *args, **kwargs)
 
-    def op(self) -> ops.Node:
+    def op(self) -> ops.Node:  # noqa: D102
         return self._arg
 
     def _find_backends(self) -> tuple[list[BaseBackend], bool]:

ibis/expr/types/generic.py

@@ -59,7 +59,8 @@ def name(self, name):
         return op.to_expr()
 
     # TODO(kszucs): should rename to dtype
-    def type(self):
+    def type(self) -> dt.DataType:
+        """Return the [DataType] of this expression."""
         return self.op().output_dtype
 
     def hash(self, how: str = "fnv") -> ir.IntegerValue:
@@ -482,11 +483,25 @@ def desc(self) -> ir.Value:
         return ops.SortKey(self, ascending=False).to_expr()
 
     @util.deprecated(as_of="4.1", removed_in="5.0", instead="use `.as_table()`")
-    def to_projection(self) -> ir.Table:
+    def to_projection(self) -> ir.Table:  # noqa: D102
         return self.as_table()
 
     def as_table(self) -> ir.Table:
-        """Promote this value expression to a projection."""
+        """Promote the expression to a table.
+
+        Returns
+        -------
+        Table
+            A table expression
+
+        Examples
+        --------
+        >>> t = ibis.table(dict(a="str"), name="t")
+        >>> expr = t.a.length().name("len").as_table()
+        >>> expected = t.select(len=t.a.length())
+        >>> expr.equals(expected)
+        True
+        """
         from ibis.expr.analysis import find_immediate_parent_tables
 
         roots = find_immediate_parent_tables(self.op())
@@ -510,6 +525,29 @@ def __rich_console__(self, console, options):
         return console.render(repr(self.execute()), options=options)
 
     def as_table(self) -> ir.Table:
+        """Promote the scalar expression to a table.
+
+        Returns
+        -------
+        Table
+            A table expression
+
+        Examples
+        --------
+        Promote an aggregation to a table
+
+        >>> t = ibis.table(dict(a="str"), name="t")
+        >>> expr = t.a.length().sum().name("len").as_table()
+        >>> isinstance(expr, ir.Table)
+        True
+
+        Promote a literal value to a table
+
+        >>> import ibis.expr.types as ir
+        >>> lit = ibis.literal(1).name("a").as_table()
+        >>> isinstance(lit, ir.Table)
+        True
+        """
         from ibis.expr.analysis import (
             find_first_base_table,
             is_scalar_reduction,
@@ -779,46 +817,121 @@ def value_counts(self, metric_name: str = "count") -> ir.Table:
         )
 
     def first(self) -> Column:
+        """Return the first value of a column.
+
+        Equivalent to SQL's `FIRST_VALUE` window function.
+        """
         return ops.FirstValue(self).to_expr()
 
     def last(self) -> Column:
+        """Return the last value of a column.
+
+        Equivalent to SQL's `LAST_VALUE` window function.
+        """
         return ops.LastValue(self).to_expr()
 
-    def rank(self) -> Column:
+    def rank(self) -> ir.IntegerColumn:
+        """Compute position of first element within each equal-value group in sorted order.
+
+        Equivalent to SQL's `RANK()` window function.
+
+        Examples
+        --------
+        values   ranks
+        1        0
+        1        0
+        2        2
+        2        2
+        2        2
+        3        5
+
+        Returns
+        -------
+        Int64Column
+            The min rank
+        """
         return ops.MinRank(self).to_expr()
 
-    def dense_rank(self) -> Column:
+    def dense_rank(self) -> ir.IntegerColumn:
+        """Position of first element within each group of equal values.
+
+        Values are returned in sorted order and duplicate values are ignored.
+
+        Equivalent to SQL's `DENSE_RANK()`.
+
+        Examples
+        --------
+        values   ranks
+        1        0
+        1        0
+        2        1
+        2        1
+        2        1
+        3        2
+
+        Returns
+        -------
+        IntegerColumn
+            The rank
+        """
         return ops.DenseRank(self).to_expr()
 
     def percent_rank(self) -> Column:
+        """Return the relative rank of the values in the column."""
         return ops.PercentRank(self).to_expr()
 
     def cume_dist(self) -> Column:
-        import ibis.expr.operations as ops
-
+        """Return the cumulative distribution over a window."""
         return ops.CumeDist(self).to_expr()
 
     def cummin(self) -> Column:
+        """Return the cumulative min over a window."""
         return ops.CumulativeMin(self).to_expr()
 
     def cummax(self) -> Column:
+        """Return the cumulative max over a window."""
         return ops.CumulativeMax(self).to_expr()
 
     def lag(
         self,
         offset: int | ir.IntegerValue | None = None,
         default: Value | None = None,
     ) -> Column:
+        """Return the row located at `offset` rows **before** the current row.
+
+        Parameters
+        ----------
+        offset
+            Index of row to select
+        default
+            Value used if no row exists at `offset`
+        """
         return ops.Lag(self, offset, default).to_expr()
 
     def lead(
         self,
         offset: int | ir.IntegerValue | None = None,
         default: Value | None = None,
     ) -> Column:
+        """Return the row located at `offset` rows **after** the current row.
+
+        Parameters
+        ----------
+        offset
+            Index of row to select
+        default
+            Value used if no row exists at `offset`
+        """
         return ops.Lead(self, offset, default).to_expr()
 
     def ntile(self, buckets: int | ir.IntegerValue) -> ir.IntegerColumn:
+        """Return the integer number of a partitioning of the column values.
+
+        Parameters
+        ----------
+        buckets
+            Number of buckets to partition into
+        """
         return ops.NTile(self, buckets).to_expr()
 
     def nth(self, n: int | ir.IntegerValue) -> Column:

ibis/expr/types/groupby.py

@@ -85,6 +85,7 @@ def _column_wrapper(self, attr):
             return GroupedArray(col, self)
 
     def aggregate(self, metrics=None, **kwds):
+        """Compute aggregates over a group by."""
         return self.table.aggregate(metrics, by=self.by, having=self._having, **kwds)
 
     agg = aggregate
@@ -290,14 +291,17 @@ def __init__(self, arr, parent):
     group_concat = _group_agg_dispatch('group_concat')
 
     def summary(self, exact_nunique=False):
+        """Summarize a column.
+
+        Parameters
+        ----------
+        exact_nunique
+            Whether to compute an exact count distinct.
+        """
         metric = self.arr.summary(exact_nunique=exact_nunique)
         return self.parent.aggregate(metric)
 
 
 class GroupedNumbers(GroupedArray):
     mean = _group_agg_dispatch('mean')
     sum = _group_agg_dispatch('sum')
-
-    def summary(self, exact_nunique=False):
-        metric = self.arr.summary(exact_nunique=exact_nunique)
-        return self.parent.aggregate(metric)

ibis/expr/types/logical.py

@@ -78,23 +78,35 @@ class BooleanScalar(NumericScalar, BooleanValue):
 @public
 class BooleanColumn(NumericColumn, BooleanValue):
     def any(self, where: BooleanValue | None = None) -> BooleanValue:
+        """Return whether at least one element is `True`.
+
+        Parameters
+        ----------
+        where
+            Optional filter for the aggregation
+        """
         import ibis.expr.analysis as an
 
         return an._make_any(self, ops.Any, where=where)
 
     def notany(self, where: BooleanValue | None = None) -> BooleanValue:
+        """Return whether no elements are `True`."""
         import ibis.expr.analysis as an
 
         return an._make_any(self, ops.NotAny, where=where)
 
     def all(self, where: BooleanValue | None = None) -> BooleanScalar:
+        """Return whether all elements are `True`."""
         return ops.All(self, where=where).to_expr()
 
     def notall(self, where: BooleanValue | None = None) -> BooleanScalar:
+        """Return whether not all elements are `True`."""
         return ops.NotAll(self, where=where).to_expr()
 
     def cumany(self) -> BooleanColumn:
+        """Accumulate the `any` aggregate."""
         return ops.CumulativeAny(self).to_expr()
 
     def cumall(self) -> BooleanColumn:
+        """Accumulate the `all` aggregate."""
         return ops.CumulativeAll(self).to_expr()

ibis/expr/types/numeric.py

@@ -466,6 +466,7 @@ def mean(
         return ops.Mean(self, where=where).to_expr()
 
     def cummean(self) -> NumericColumn:
+        """Return the cumulative mean of the input."""
         return ops.CumulativeMean(self).to_expr()
 
     def sum(
@@ -487,6 +488,7 @@ def sum(
         return ops.Sum(self, where=where).to_expr()
 
     def cumsum(self) -> NumericColumn:
+        """Return the cumulative sum of the input."""
         return ops.CumulativeSum(self).to_expr()
 
     def bucket(