New docs examples (#3226)

py-polars/polars/internals/expr.py

@@ -3944,6 +3944,23 @@ def replace(self, pattern: str, value: str) -> Expr:
             Regex pattern.
         value
             Replacement string.
+
+        Examples
+        --------
+
+        >>> df = pl.DataFrame({"id": [1, 2], "text": ["123abc", "abc456"]})
+        >>> df.with_column(pl.col("text").str.replace(r"abc\b", "ABC"))
+        shape: (2, 2)
+        ┌─────┬────────┐
+        │ id  ┆ text   │
+        │ --- ┆ ---    │
+        │ i64 ┆ str    │
+        ╞═════╪════════╡
+        │ 1   ┆ 123ABC │
+        ├╌╌╌╌╌┼╌╌╌╌╌╌╌╌┤
+        │ 2   ┆ abc456 │
+        └─────┴────────┘
+
         """
         return wrap_expr(self._pyexpr.str_replace(pattern, value))
 

py-polars/polars/internals/frame.py

@@ -1215,6 +1215,14 @@ def to_dicts(self) -> List[Dict[str, Any]]:
         Convert every row to a dictionary.
 
         Note that this is slow.
+
+        Examples
+        --------
+
+        >>> df = pl.DataFrame({"foo": [1, 2, 3], "bar": [4, 5, 6]})
+        >>> df.to_dicts()
+        [{'foo': 1, 'bar': 4}, {'foo': 2, 'bar': 5}, {'foo': 3, 'bar': 6}]
+
         """
 
         pydf = self._df
@@ -2354,6 +2362,27 @@ def replace(self, column: str, new_col: "pli.Series") -> None:
             Column to replace.
         new_col
             New column to insert.
+
+        Examples
+        --------
+
+        >>> df = pl.DataFrame({"foo": [1, 2, 3], "bar": [4, 5, 6]})
+        >>> s = pl.Series([10, 20, 30])
+        >>> df.replace("foo", s)  # works in-place!
+        >>> df
+        shape: (3, 2)
+        ┌─────┬─────┐
+        │ foo ┆ bar │
+        │ --- ┆ --- │
+        │ i64 ┆ i64 │
+        ╞═════╪═════╡
+        │ 10  ┆ 4   │
+        ├╌╌╌╌╌┼╌╌╌╌╌┤
+        │ 20  ┆ 5   │
+        ├╌╌╌╌╌┼╌╌╌╌╌┤
+        │ 30  ┆ 6   │
+        └─────┴─────┘
+
         """
         self._df.replace(column, new_col.inner())
 
@@ -5538,16 +5567,28 @@ def agg(
         -------
         Result of groupby split apply operations.
 
-
         Examples
         --------
 
-        >>> df.groupby(["foo", "bar"]).agg(
+        >>> df = pl.DataFrame(
+        ...     {"foo": ["one", "two", "two", "one", "two"], "bar": [5, 3, 2, 4, 1]}
+        ... )
+        >>> df.groupby("foo").agg(
         ...     [
-        ...         pl.sum("ham"),
-        ...         pl.col("spam").tail(4).sum(),
+        ...         pl.sum("bar").suffix("_sum"),
+        ...         pl.col("bar").sort().tail(2).sum().suffix("_tail_sum"),
         ...     ]
-        ... )  # doctest: +SKIP
+        ... )
+        shape: (2, 3)
+        ┌─────┬─────────┬──────────────┐
+        │ foo ┆ bar_sum ┆ bar_tail_sum │
+        │ --- ┆ ---     ┆ ---          │
+        │ str ┆ i64     ┆ i64          │
+        ╞═════╪═════════╪══════════════╡
+        │ one ┆ 9       ┆ 9            │
+        ├╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
+        │ two ┆ 6       ┆ 5            │
+        └─────┴─────────┴──────────────┘
 
         """
 

py-polars/polars/internals/series.py

@@ -951,6 +951,17 @@ def entropy(self, base: float = math.e) -> Optional[float]:
         where `pk` are discrete probabilities.
 
         This routine will normalize pk if they don’t sum to 1.
+
+        Examples
+        --------
+
+        >>> a = pl.Series([0.99, 0.005, 0.005])
+        >>> a.entropy()
+        0.06293300616044681
+        >>> b = pl.Series([0.65, 0.10, 0.25])
+        >>> b.entropy()
+        0.8568409950394724
+
         """
         return pli.select(pli.lit(self).entropy(base)).to_series()[0]
 
@@ -4022,6 +4033,19 @@ def replace(self, pattern: str, value: str) -> Series:
             A valid regex pattern.
         value
             Substring to replace.
+
+        Examples
+        --------
+
+        >>> s = pl.Series(["123abc", "abc456"])
+        >>> s.str.replace(r"abc\b", "ABC")
+        shape: (2,)
+        Series: '' [str]
+        [
+                "123ABC"
+                "abc456"
+        ]
+
         """
         return wrap_s(self._s.str_replace(pattern, value))