Add docs examples (#2730)

pola-rs · Feb 22, 2022 · f871916 · f871916
1 parent 7c99c24
commit f871916
Show file tree

Hide file tree

Showing 2 changed files with 111 additions and 3 deletions.
diff --git a/py-polars/polars/internals/expr.py b/py-polars/polars/internals/expr.py
@@ -1382,6 +1382,30 @@ def repeat_by(self, by: Union["Expr", str]) -> "Expr":
         Returns
         -------
         Series of type List
+
+        Examples
+        --------
+
+        >>> df = pl.DataFrame(
+        ...     {
+        ...         "a": ["x", "y", "z"],
+        ...         "n": [1, 2, 3],
+        ...     }
+        ... )
+        >>> df.select(pl.col("a").repeat_by("n"))
+        shape: (3, 1)
+        ┌─────────────────┐
+        │ a               │
+        │ ---             │
+        │ list [str]      │
+        ╞═════════════════╡
+        │ ["x"]           │
+        ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
+        │ ["y", "y"]      │
+        ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
+        │ ["z", "z", "z"] │
+        └─────────────────┘
+
         """
         by = expr_to_lit_or_expr(by, False)
         return wrap_expr(self._pyexpr.repeat_by(by._pyexpr))
@@ -2355,6 +2379,22 @@ def extend_constant(
             The value to extend the Series with. This value may be None to fill with nulls.
         n
             The number of values to extend.
+
+        Examples
+        --------
+
+        >>> s = pl.Series([1, 2, 3])
+        >>> s.extend_constant(99, n=2)
+        shape: (5,)
+        Series: '' [i64]
+        [
+                1
+                2
+                3
+                99
+                99
+        ]
+
         """
         return wrap_expr(self._pyexpr.extend_constant(value, n))
 
@@ -2378,7 +2418,7 @@ def str(self) -> "ExprStringNameSpace":
     @property
     def arr(self) -> "ExprListNameSpace":
         """
-        Create an object namespace of all datetime related methods.
+        Create an object namespace of all list related methods.
         """
         return ExprListNameSpace(self)
 

diff --git a/py-polars/polars/internals/frame.py b/py-polars/polars/internals/frame.py
@@ -2299,6 +2299,30 @@ def pipe(self, func: Callable[..., Any], *args: Any, **kwargs: Any) -> Any:
             Arguments.
         kwargs
             Keyword arguments.
+
+        Examples
+        --------
+
+        >>> def cast_str_to_int(data, col_name):
+        ...     return data.with_column(pl.col(col_name).cast(pl.Int64))
+        ...
+        >>> df = pl.DataFrame({"a": [1, 2, 3, 4], "b": ["10", "20", "30", "40"]})
+        >>> df.pipe(cast_str_to_int, col_name="b")
+        shape: (4, 2)
+        ┌─────┬─────┐
+        │ a   ┆ b   │
+        │ --- ┆ --- │
+        │ i64 ┆ i64 │
+        ╞═════╪═════╡
+        │ 1   ┆ 10  │
+        ├╌╌╌╌╌┼╌╌╌╌╌┤
+        │ 2   ┆ 20  │
+        ├╌╌╌╌╌┼╌╌╌╌╌┤
+        │ 3   ┆ 30  │
+        ├╌╌╌╌╌┼╌╌╌╌╌┤
+        │ 4   ┆ 40  │
+        └─────┴─────┘
+
         """
         return func(self, *args, **kwargs)
 
@@ -3528,8 +3552,35 @@ def melt(
         value_vars
             Values to use as identifier variables.
 
-        Returns
-        -------
+        Examples
+        --------
+
+        >>> df = pl.DataFrame(
+        ...     {
+        ...         "a": ["x", "y", "z"],
+        ...         "b": [1, 3, 5],
+        ...         "c": [2, 4, 6],
+        ...     }
+        ... )
+        >>> df.melt(id_vars="a", value_vars=["b", "c"])
+        shape: (6, 3)
+        ┌─────┬──────────┬───────┐
+        │ a   ┆ variable ┆ value │
+        │ --- ┆ ---      ┆ ---   │
+        │ str ┆ str      ┆ i64   │
+        ╞═════╪══════════╪═══════╡
+        │ x   ┆ b        ┆ 1     │
+        ├╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌┤
+        │ y   ┆ b        ┆ 3     │
+        ├╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌┤
+        │ z   ┆ b        ┆ 5     │
+        ├╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌┤
+        │ x   ┆ c        ┆ 2     │
+        ├╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌┤
+        │ y   ┆ c        ┆ 4     │
+        ├╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌┤
+        │ z   ┆ c        ┆ 6     │
+        └─────┴──────────┴───────┘
 
         """
         if isinstance(value_vars, str):
@@ -4890,6 +4941,23 @@ def median(self) -> DataFrame:
     def agg_list(self) -> DataFrame:
         """
         Aggregate the groups into Series.
+
+        Examples
+        --------
+
+        >>> df = pl.DataFrame({"a": ["one", "two", "one", "two"], "b": [1, 2, 3, 4]})
+        >>> df.groupby("a").agg_list()
+        shape: (2, 2)
+        ┌─────┬────────────┐
+        │ a   ┆ b          │
+        │ --- ┆ ---        │
+        │ str ┆ list [i64] │
+        ╞═════╪════════════╡
+        │ one ┆ [1, 3]     │
+        ├╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌┤
+        │ two ┆ [2, 4]     │
+        └─────┴────────────┘
+
         """
         return self.agg(pli.all().list())