bonus docstring examples

py-polars/polars/dataframe/frame.py

@@ -4533,9 +4533,13 @@ def drop_nulls(
         ...     {
         ...         "foo": [1, 2, 3],
         ...         "bar": [6, None, 8],
-        ...         "ham": ["a", "b", "c"],
+        ...         "ham": ["a", "b", None],
         ...     }
         ... )
+
+        The default behavior of this method is to drop rows where any single
+        value of the row is null.
+
         >>> df.drop_nulls()
         shape: (2, 3)
         ┌─────┬─────┬─────┐
@@ -4544,13 +4548,26 @@ def drop_nulls(
         │ i64 ┆ i64 ┆ str │
         ╞═════╪═════╪═════╡
         │ 1   ┆ 6   ┆ a   │
-        │ 3   ┆ 8   ┆ c   │
         └─────┴─────┴─────┘
 
-        This method drops rows where any single value of the row is null.
+        This behaviour can be constrained to consider only a subset of columns, as
+        defined by name or with a selector. For example, dropping rows if there is
+        a null in any of the integer columns:
 
-        Below are some example snippets that show how you could drop null values based
-        on other conditions
+        >>> import polars.selectors as cs
+        >>> df.drop_nulls(subset=cs.integer())
+        shape: (2, 3)
+        ┌─────┬─────┬──────┐
+        │ foo ┆ bar ┆ ham  │
+        │ --- ┆ --- ┆ ---  │
+        │ i64 ┆ i64 ┆ str  │
+        ╞═════╪═════╪══════╡
+        │ 1   ┆ 6   ┆ a    │
+        │ 3   ┆ 8   ┆ null │
+        └─────┴─────┴──────┘
+
+        Below are some additional examples that show how to drop null
+        values based on other conditions.
 
         >>> df = pl.DataFrame(
         ...     {
@@ -6568,23 +6585,45 @@ def pivot(
         --------
         >>> df = pl.DataFrame(
         ...     {
-        ...         "foo": ["one", "one", "one", "two", "two", "two"],
-        ...         "bar": ["A", "B", "C", "A", "B", "C"],
+        ...         "foo": ["one", "one", "two", "two", "one", "two"],
+        ...         "bar": ["y", "y", "y", "x", "x", "x"],
         ...         "baz": [1, 2, 3, 4, 5, 6],
         ...     }
         ... )
+        >>> df.pivot(values="baz", index="foo", columns="bar", aggregate_function="sum")
+        shape: (2, 3)
+        ┌─────┬─────┬─────┐
+        │ foo ┆ y   ┆ x   │
+        │ --- ┆ --- ┆ --- │
+        │ str ┆ i64 ┆ i64 │
+        ╞═════╪═════╪═════╡
+        │ one ┆ 3   ┆ 5   │
+        │ two ┆ 3   ┆ 10  │
+        └─────┴─────┴─────┘
+
+        Pivot using selectors to determine the index/values/columns:
+
+        >>> import polars.selectors as cs
         >>> df.pivot(
-        ...     values="baz", index="foo", columns="bar", aggregate_function="first"
+        ...     values=cs.numeric(),
+        ...     index=cs.string(),
+        ...     columns=cs.string(),
+        ...     aggregate_function="sum",
+        ...     sort_columns=True,
+        ... ).sort(
+        ...     by=cs.string(),
         ... )
-        shape: (2, 4)
-        ┌─────┬─────┬─────┬─────┐
-        │ foo ┆ A   ┆ B   ┆ C   │
-        │ --- ┆ --- ┆ --- ┆ --- │
-        │ str ┆ i64 ┆ i64 ┆ i64 │
-        ╞═════╪═════╪═════╪═════╡
-        │ one ┆ 1   ┆ 2   ┆ 3   │
-        │ two ┆ 4   ┆ 5   ┆ 6   │
-        └─────┴─────┴─────┴─────┘
+        shape: (4, 6)
+        ┌─────┬─────┬──────┬──────┬──────┬──────┐
+        │ foo ┆ bar ┆ one  ┆ two  ┆ x    ┆ y    │
+        │ --- ┆ --- ┆ ---  ┆ ---  ┆ ---  ┆ ---  │
+        │ str ┆ str ┆ i64  ┆ i64  ┆ i64  ┆ i64  │
+        ╞═════╪═════╪══════╪══════╪══════╪══════╡
+        │ one ┆ x   ┆ 5    ┆ null ┆ 5    ┆ null │
+        │ one ┆ y   ┆ 3    ┆ null ┆ null ┆ 3    │
+        │ two ┆ x   ┆ null ┆ 10   ┆ 10   ┆ null │
+        │ two ┆ y   ┆ null ┆ 3    ┆ null ┆ 3    │
+        └─────┴─────┴──────┴──────┴──────┴──────┘
 
         Run an expression as aggregation function
 

py-polars/polars/lazyframe/frame.py

@@ -4465,9 +4465,13 @@ def drop_nulls(
         ...     {
         ...         "foo": [1, 2, 3],
         ...         "bar": [6, None, 8],
-        ...         "ham": ["a", "b", "c"],
+        ...         "ham": ["a", "b", None],
         ...     }
         ... )
+
+        The default behavior of this method is to drop rows where any single
+        value of the row is null.
+
         >>> lf.drop_nulls().collect()
         shape: (2, 3)
         ┌─────┬─────┬─────┐
@@ -4476,13 +4480,28 @@ def drop_nulls(
         │ i64 ┆ i64 ┆ str │
         ╞═════╪═════╪═════╡
         │ 1   ┆ 6   ┆ a   │
-        │ 3   ┆ 8   ┆ c   │
         └─────┴─────┴─────┘
 
+        This behaviour can be constrained to consider only a subset of columns, as
+        defined by name or with a selector. For example, dropping rows if there is
+        a null in any of the integer columns:
+
+        >>> import polars.selectors as cs
+        >>> lf.drop_nulls(subset=cs.integer()).collect()
+        shape: (2, 3)
+        ┌─────┬─────┬──────┐
+        │ foo ┆ bar ┆ ham  │
+        │ --- ┆ --- ┆ ---  │
+        │ i64 ┆ i64 ┆ str  │
+        ╞═════╪═════╪══════╡
+        │ 1   ┆ 6   ┆ a    │
+        │ 3   ┆ 8   ┆ null │
+        └─────┴─────┴──────┘
+
         This method drops a row if any single value of the row is null.
 
-        Below are some example snippets that show how you could drop null values based
-        on other conditions:
+        Below are some example snippets that show how you could drop null
+        values based on other conditions:
 
         >>> lf = pl.LazyFrame(
         ...     {