Docs examples (#3205)

py-polars/polars/internals/expr.py

@@ -3041,6 +3041,23 @@ def __init__(self, expr: Expr):
     def lengths(self) -> Expr:
         """
         Get the length of the arrays as UInt32.
+
+        Examples
+        --------
+
+        >>> df = pl.DataFrame({"foo": [1, 2], "bar": [["a", "b"], ["c"]]})
+        >>> df.select(pl.col("bar").arr.lengths())
+        shape: (2, 1)
+        ┌─────┐
+        │ bar │
+        │ --- │
+        │ u32 │
+        ╞═════╡
+        │ 2   │
+        ├╌╌╌╌╌┤
+        │ 1   │
+        └─────┘
+
         """
         return wrap_expr(self._pyexpr.arr_lengths())
 
@@ -3186,18 +3203,75 @@ def get(self, index: int) -> "Expr":
         ----------
         index
             Index to return per sublist
+
+        Examples
+        --------
+
+        >>> df = pl.DataFrame({"foo": [[3, 2, 1], [], [1, 2]]})
+        >>> df.select(pl.col("foo").arr.get(0))
+        shape: (3, 1)
+        ┌──────┐
+        │ foo  │
+        │ ---  │
+        │ i64  │
+        ╞══════╡
+        │ 3    │
+        ├╌╌╌╌╌╌┤
+        │ null │
+        ├╌╌╌╌╌╌┤
+        │ 1    │
+        └──────┘
+
         """
         return wrap_expr(self._pyexpr.lst_get(index))
 
     def first(self) -> "Expr":
         """
         Get the first value of the sublists.
+
+        Examples
+        --------
+
+        >>> df = pl.DataFrame({"foo": [[3, 2, 1], [], [1, 2]]})
+        >>> df.select(pl.col("foo").arr.first())
+        shape: (3, 1)
+        ┌──────┐
+        │ foo  │
+        │ ---  │
+        │ i64  │
+        ╞══════╡
+        │ 3    │
+        ├╌╌╌╌╌╌┤
+        │ null │
+        ├╌╌╌╌╌╌┤
+        │ 1    │
+        └──────┘
+
         """
         return self.get(0)
 
     def last(self) -> "Expr":
         """
         Get the last value of the sublists.
+
+        Examples
+        --------
+
+        >>> df = pl.DataFrame({"foo": [[3, 2, 1], [], [1, 2]]})
+        >>> df.select(pl.col("foo").arr.last())
+        shape: (3, 1)
+        ┌──────┐
+        │ foo  │
+        │ ---  │
+        │ i64  │
+        ╞══════╡
+        │ 1    │
+        ├╌╌╌╌╌╌┤
+        │ null │
+        ├╌╌╌╌╌╌┤
+        │ 2    │
+        └──────┘
+
         """
         return self.get(-1)
 
@@ -3213,6 +3287,25 @@ def contains(self, item: Union[float, str, bool, int, date, datetime]) -> "Expr"
         Returns
         -------
         Boolean mask
+
+        Examples
+        --------
+
+        >>> df = pl.DataFrame({"foo": [[3, 2, 1], [], [1, 2]]})
+        >>> df.select(pl.col("foo").arr.contains(1))
+        shape: (3, 1)
+        ┌───────┐
+        │ foo   │
+        │ ---   │
+        │ bool  │
+        ╞═══════╡
+        │ true  │
+        ├╌╌╌╌╌╌╌┤
+        │ false │
+        ├╌╌╌╌╌╌╌┤
+        │ true  │
+        └───────┘
+
         """
         return wrap_expr(self._pyexpr).map(lambda s: s.arr.contains(item))
 

py-polars/polars/internals/functions.py

@@ -139,6 +139,19 @@ def arg_where(mask: "pli.Series") -> "pli.Series":
     Returns
     -------
     UInt32 Series
+
+    Examples
+    --------
+
+    >>> df = pl.DataFrame({"a": [1, 2, 3, 4, 5]})
+    >>> pl.arg_where(df.select(pl.col("a") % 2 == 0).to_series())
+    shape: (2,)
+    Series: '' [u32]
+    [
+            1
+            3
+    ]
+
     """
     return mask.arg_true()
 

py-polars/polars/internals/series.py

@@ -3752,6 +3752,21 @@ def lengths(self) -> Series:
         Returns
         -------
         Series[u32]
+
+        Examples
+        --------
+
+        >>> s = pl.Series(["foo", "bar", "hello", "world"])
+        >>> s.str.lengths()
+        shape: (4,)
+        Series: '' [u32]
+        [
+                3
+                3
+                5
+                5
+        ]
+
         """
         return wrap_s(self._s.str_lengths())
 
@@ -4076,7 +4091,7 @@ def slice(self, start: int, length: Optional[int] = None) -> Series:
 
 class ListNameSpace:
     """
-    Series.dt namespace.
+    Series.arr namespace.
     """
 
     def __init__(self, series: Series):
@@ -4085,6 +4100,19 @@ def __init__(self, series: Series):
     def lengths(self) -> Series:
         """
         Get the length of the arrays as UInt32.
+
+        Examples
+        --------
+
+        >>> s = pl.Series([[1, 2, 3], [5]])
+        >>> s.arr.lengths()
+        shape: (2,)
+        Series: '' [u32]
+        [
+                3
+                1
+        ]
+
         """
         return wrap_s(self._s.arr_lengths())
 
@@ -4169,6 +4197,19 @@ def join(self, separator: str) -> "Series":
         Returns
         -------
         Series of dtype Utf8
+
+        Examples
+        --------
+
+        >>> s = pl.Series([["foo", "bar"], ["hello", "world"]])
+        >>> s.arr.join(separator="-")
+        shape: (2,)
+        Series: '' [str]
+        [
+                "foo-bar"
+                "hello-world"
+        ]
+
         """
         return pli.select(pli.lit(wrap_s(self._s)).arr.join(separator)).to_series()