docs(python): Add "See Also" for arg_sort and arg_sort_by (#15348)

py-polars/polars/expr/expr.py

@@ -2131,11 +2131,17 @@ def arg_sort(self, *, descending: bool = False, nulls_last: bool = False) -> Sel
         Expr
             Expression of data type :class:`UInt32`.
 
+        See Also
+        --------
+        Expr.gather: Take values by index.
+        Expr.rank : Get the rank of each row.
+
         Examples
         --------
         >>> df = pl.DataFrame(
         ...     {
         ...         "a": [20, 10, 30],
+        ...         "b": [1, 2, 3],
         ...     }
         ... )
         >>> df.select(pl.col("a").arg_sort())
@@ -2149,6 +2155,20 @@ def arg_sort(self, *, descending: bool = False, nulls_last: bool = False) -> Sel
         │ 0   │
         │ 2   │
         └─────┘
+
+        Use gather to apply the arg sort to other columns.
+
+        >>> df.select(pl.col("b").gather(pl.col("a").arg_sort()))
+        shape: (3, 1)
+        ┌─────┐
+        │ b   │
+        │ --- │
+        │ i64 │
+        ╞═════╡
+        │ 2   │
+        │ 1   │
+        │ 3   │
+        └─────┘
         """
         return self._from_pyexpr(self._pyexpr.arg_sort(descending, nulls_last))
 

py-polars/polars/functions/lazy.py

@@ -1539,7 +1539,7 @@ def arg_sort_by(
     descending: bool | Sequence[bool] = False,
 ) -> Expr:
     """
-    Return the row indices that would sort the columns.
+    Return the row indices that would sort the column(s).
 
     Parameters
     ----------
@@ -1552,6 +1552,11 @@ def arg_sort_by(
         Sort in descending order. When sorting by multiple columns, can be specified
         per column by passing a sequence of booleans.
 
+    See Also
+    --------
+    Expr.gather: Take values by index.
+    Expr.rank : Get the rank of each row.
+
     Examples
     --------
     Pass a single column name to compute the arg sort by that column.
@@ -1560,6 +1565,7 @@ def arg_sort_by(
     ...     {
     ...         "a": [0, 1, 1, 0],
     ...         "b": [3, 2, 3, 2],
+    ...         "c": [1, 2, 3, 4],
     ...     }
     ... )
     >>> df.select(pl.arg_sort_by("a"))
@@ -1590,6 +1596,21 @@ def arg_sort_by(
     │ 0   │
     │ 3   │
     └─────┘
+
+    Use gather to apply the arg sort to other columns.
+
+    >>> df.select(pl.col("c").gather(pl.arg_sort_by("a")))
+    shape: (4, 1)
+    ┌─────┐
+    │ c   │
+    │ --- │
+    │ i64 │
+    ╞═════╡
+    │ 1   │
+    │ 4   │
+    │ 2   │
+    │ 3   │
+    └─────┘
     """
     exprs = parse_as_list_of_expressions(exprs, *more_exprs)
 

py-polars/polars/series/series.py

@@ -3459,6 +3459,11 @@ def arg_sort(self, *, descending: bool = False, nulls_last: bool = False) -> Ser
         nulls_last
             Place null values last instead of first.
 
+        See Also
+        --------
+        Series.gather: Take values by index.
+        Series.rank : Get the rank of each row.
+
         Examples
         --------
         >>> s = pl.Series("a", [5, 3, 4, 1, 2])