Skip to content

Commit

Permalink
docs(python): Add missing examples of series/list.py (#13423)
Browse files Browse the repository at this point in the history
  • Loading branch information
@reswqa
reswqa committed Jan 4, 2024
1 parent e9687b1 commit a0c7f58
Showing 1 changed file with 226 additions and 21 deletions.
247 changes: 226 additions & 21 deletions py-polars/polars/series/list.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -175,16 +175,72 @@ def sample(
"""

def sum(self) -> Series:
"""Sum all the arrays in the list."""
"""
Sum all the arrays in the list.
Examples
--------
>>> s = pl.Series("values", [[1], [2, 3]])
>>> s.list.sum()
shape: (2,)
Series: 'values' [i64]
[
1
5
]
"""

def max(self) -> Series:
"""Compute the max value of the arrays in the list."""
"""
Compute the max value of the arrays in the list.
Examples
--------
>>> s = pl.Series("values", [[4, 1], [2, 3]])
>>> s.list.max()
shape: (2,)
Series: 'values' [i64]
[
4
3
]
"""

def min(self) -> Series:
"""Compute the min value of the arrays in the list."""
"""
Compute the min value of the arrays in the list.
Examples
--------
>>> s = pl.Series("values", [[4, 1], [2, 3]])
>>> s.list.min()
shape: (2,)
Series: 'values' [i64]
[
1
2
]
"""

def mean(self) -> Series:
"""Compute the mean value of the arrays in the list."""
"""
Compute the mean value of the arrays in the list.
Examples
--------
>>> s = pl.Series("values", [[3, 1], [3, 3]])
>>> s.list.mean()
shape: (2,)
Series: 'values' [f64]
[
2.0
3.0
]
"""

def sort(self, *, descending: bool = False) -> Series:
"""
Expand Down Expand Up @@ -216,7 +272,21 @@ def sort(self, *, descending: bool = False) -> Series:
"""

def reverse(self) -> Series:
"""Reverse the arrays in the list."""
"""
Reverse the arrays in the list.
Examples
--------
>>> s = pl.Series("a", [[3, 2, 1], [9, 1, 2]])
>>> s.list.reverse()
shape: (2,)
Series: 'a' [list[i64]]
[
[1, 2, 3]
[2, 1, 9]
]
"""

def unique(self, *, maintain_order: bool = False) -> Series:
"""
Expand All @@ -227,6 +297,17 @@ def unique(self, *, maintain_order: bool = False) -> Series:
maintain_order
Maintain order of data. This requires more work.
Examples
--------
>>> s = pl.Series("a", [[1, 1, 2], [2, 3, 3]])
>>> s.list.unique()
shape: (2,)
Series: 'a' [list[i64]]
[
[1, 2]
[2, 3]
]
"""

def concat(self, other: list[Series] | Series | list[Any]) -> Series:
Expand All @@ -238,6 +319,18 @@ def concat(self, other: list[Series] | Series | list[Any]) -> Series:
other
Columns to concat into a List Series
Examples
--------
>>> s1 = pl.Series("a", [["a", "b"], ["c"]])
>>> s2 = pl.Series("b", [["c"], ["d", None]])
>>> s1.list.concat(s2)
shape: (2,)
Series: 'a' [list[str]]
[
["a", "b", "c"]
["c", "d", null]
]
"""

def get(self, index: int | Series | list[int]) -> Series:
Expand All @@ -253,6 +346,18 @@ def get(self, index: int | Series | list[int]) -> Series:
index
Index to return per sublist
Examples
--------
>>> s = pl.Series("a", [[3, 2, 1], [], [1, 2]])
>>> s.list.get(0)
shape: (3,)
Series: 'a' [i64]
[
3
null
1
]
"""

def gather(
Expand All @@ -276,6 +381,19 @@ def gather(
True -> set as null
False -> raise an error
Note that defaulting to raising an error is much cheaper
Examples
--------
>>> s = pl.Series("a", [[3, 2, 1], [], [1, 2]])
>>> s.list.gather([0, 2], null_on_oob=True)
shape: (3,)
Series: 'a' [list[i64]]
[
[3, 1]
[null, null]
[1, null]
]
"""

def __getitem__(self, item: int) -> Series:
Expand Down Expand Up @@ -311,10 +429,40 @@ def join(self, separator: IntoExpr) -> Series:
"""

def first(self) -> Series:
"""Get the first value of the sublists."""
"""
Get the first value of the sublists.
Examples
--------
>>> s = pl.Series("a", [[3, 2, 1], [], [1, 2]])
>>> s.list.first()
shape: (3,)
Series: 'a' [i64]
[
3
null
1
]
"""

def last(self) -> Series:
"""Get the last value of the sublists."""
"""
Get the last value of the sublists.
Examples
--------
>>> s = pl.Series("a", [[3, 2, 1], [], [1, 2]])
>>> s.list.last()
shape: (3,)
Series: 'a' [i64]
[
1
null
2
]
"""

def contains(self, item: float | str | bool | int | date | datetime) -> Series:
"""
Expand All @@ -330,6 +478,18 @@ def contains(self, item: float | str | bool | int | date | datetime) -> Series:
Series
Series of data type :class:`Boolean`.
Examples
--------
>>> s = pl.Series("a", [[3, 2, 1], [], [1, 2]])
>>> s.list.contains(1)
shape: (3,)
Series: 'a' [bool]
[
true
false
true
]
"""

def arg_min(self) -> Series:
Expand All @@ -342,6 +502,17 @@ def arg_min(self) -> Series:
Series of data type :class:`UInt32` or :class:`UInt64`
(depending on compilation).
Examples
--------
>>> s = pl.Series("a", [[1, 2], [2, 1]])
>>> s.list.arg_min()
shape: (2,)
Series: 'a' [u32]
[
0
1
]
"""

def arg_max(self) -> Series:
Expand All @@ -354,6 +525,17 @@ def arg_max(self) -> Series:
Series of data type :class:`UInt32` or :class:`UInt64`
(depending on compilation).
Examples
--------
>>> s = pl.Series("a", [[1, 2], [2, 1]])
>>> s.list.arg_max()
shape: (2,)
Series: 'a' [u32]
[
1
0
]
"""

def diff(self, n: int = 1, null_behavior: NullBehavior = "ignore") -> Series:
Expand Down Expand Up @@ -547,6 +729,20 @@ def count_matches(
element
An expression that produces a single value
Examples
--------
>>> s = pl.Series("a", [[0], [1], [1, 2, 3, 2], [1, 2, 1], [4, 4]])
>>> s.list.count_matches(1)
shape: (5,)
Series: 'a' [u32]
[
0
1
1
2
0
]
"""

def to_array(self, width: int) -> Series:
Expand Down Expand Up @@ -667,20 +863,15 @@ def eval(self, expr: Expr, *, parallel: bool = False) -> Series:
Examples
--------
>>> df = pl.DataFrame({"a": [1, 8, 3], "b": [4, 5, 2]})
>>> df.with_columns(
... pl.concat_list(["a", "b"]).list.eval(pl.element().rank()).alias("rank")
... )
shape: (3, 3)
┌─────┬─────┬────────────┐
│ a ┆ b ┆ rank │
│ --- ┆ --- ┆ --- │
│ i64 ┆ i64 ┆ list[f64] │
╞═════╪═════╪════════════╡
│ 1 ┆ 4 ┆ [1.0, 2.0] │
│ 8 ┆ 5 ┆ [2.0, 1.0] │
│ 3 ┆ 2 ┆ [2.0, 1.0] │
└─────┴─────┴────────────┘
>>> s = pl.Series("a", [[1, 4], [8, 5], [3, 2]])
>>> s.list.eval(pl.element().rank())
shape: (3,)
Series: 'a' [list[f64]]
[
[1.0, 2.0]
[2.0, 1.0]
[2.0, 1.0]
]
"""

Expand Down Expand Up @@ -772,6 +963,20 @@ def set_symmetric_difference(self, other: Series) -> Series:
other
Right hand side of the set operation.
Examples
--------
>>> a = pl.Series([[1, 2, 3], [], [None, 3], [5, 6, 7]])
>>> b = pl.Series([[2, 3, 4], [3], [3, 4, None], [6, 8]])
>>> a.list.set_symmetric_difference(b)
shape: (4,)
Series: '' [list[i64]]
[
[1, 4]
[3]
[4]
[5, 7, 8]
]
""" # noqa: W505

@deprecate_renamed_function("count_matches", version="0.19.3")
Expand Down

0 comments on commit a0c7f58

Please sign in to comment.