From 13e0d333d79e3216da0f92bfc640001902096d1f Mon Sep 17 00:00:00 2001 From: tharunsuresh-code Date: Thu, 9 May 2024 13:49:47 -0700 Subject: [PATCH 1/4] docs(python): Add examples for multiple `Series` functions --- py-polars/polars/series/series.py | 153 +++++++++++++++++++++++++++++- 1 file changed, 151 insertions(+), 2 deletions(-) diff --git a/py-polars/polars/series/series.py b/py-polars/polars/series/series.py index a0e36f83d814..16c223a917e3 100644 --- a/py-polars/polars/series/series.py +++ b/py-polars/polars/series/series.py @@ -3315,6 +3315,28 @@ def limit(self, n: int = 10) -> Series: See Also -------- head + + Examples + -------- + >>> s = pl.Series("a", [1, 2, 3, 4, 5]) + >>> s.limit(3) + shape: (3,) + Series: 'a' [i64] + [ + 1 + 2 + 3 + ] + + Pass a negative value to get all rows `except` the last `abs(n)`. + + >>> s.limit(-3) + shape: (2,) + Series: 'a' [i64] + [ + 1 + 2 + ] """ return self.head(n) @@ -4065,6 +4087,28 @@ def explode(self) -> Series: -------- Series.list.explode : Explode a list column. Series.str.explode : Explode a string column. + + Examples + -------- + >>> s = pl.Series("a", [[1, 2, 3], [4,5,6]]) + >>> s + shape: (2,) + Series: 'a' [list[i64]] + [ + [1, 2, 3] + [4, 5, 6] + ] + >>> s.explode() + shape: (6,) + Series: 'a' [i64] + [ + 1 + 2 + 3 + 4 + 5 + 6 + ] """ def equals( @@ -4213,6 +4257,29 @@ def rechunk(self, *, in_place: bool = False) -> Self: ---------- in_place In place or not. + + Examples + -------- + >>> s1 = pl.Series("a", [1, 2, 3]) + >>> s1.n_chunks() + 1 + >>> s2 = pl.Series("a", [4, 5, 6]) + >>> s = pl.concat([s1, s2], rechunk=False) + >>> s.n_chunks() + 2 + >>> s.rechunk(in_place=True) + shape: (6,) + Series: 'a' [i64] + [ + 1 + 2 + 3 + 4 + 5 + 6 + ] + >>> s.n_chunks() + 1 """ opt_s = self._s.rechunk(in_place) return self if in_place else self._from_pyseries(opt_s) @@ -6279,6 +6346,26 @@ def reinterpret(self, *, signed: bool = True) -> Series: ---------- signed If True, reinterpret as `pl.Int64`. Otherwise, reinterpret as `pl.UInt64`. + + Examples + -------- + >>> s = pl.Series("a", [1, 2, 3]) + >>> s + shape: (3,) + Series: 'a' [i64] + [ + 1 + 2 + 3 + ] + >>> s.reinterpret(signed=False) + shape: (3,) + Series: 'a' [u64] + [ + 1 + 2 + 3 + ] """ def interpolate(self, method: InterpolationMethod = "linear") -> Series: @@ -7247,7 +7334,21 @@ def set_sorted(self, *, descending: bool = False) -> Self: return self._from_pyseries(self._s.set_sorted_flag(descending)) def new_from_index(self, index: int, length: int) -> Self: - """Create a new Series filled with values from the given index.""" + """ + Create a new Series filled with values from the given index. + + Examples + -------- + >>> s = pl.Series("a", [1, 2, 3, 4, 5]) + >>> s.new_from_index(1,3) + shape: (3,) + Series: 'a' [i64] + [ + 2 + 2 + 2 + ] + """ return self._from_pyseries(self._s.new_from_index(index, length)) def shrink_dtype(self) -> Series: @@ -7256,10 +7357,58 @@ def shrink_dtype(self) -> Series: Shrink to the dtype needed to fit the extrema of this [`Series`]. This can be used to reduce memory pressure. + + Examples + -------- + >>> s = pl.Series("a", [1, 2, 3, 4, 5, 6]) + >>> s + shape: (6,) + Series: 'a' [i64] + [ + 1 + 2 + 3 + 4 + 5 + 6 + ] + >>> s.shrink_dtype() + shape: (6,) + Series: 'a' [i8] + [ + 1 + 2 + 3 + 4 + 5 + 6 + ] """ def get_chunks(self) -> list[Series]: - """Get the chunks of this Series as a list of Series.""" + """ + Get the chunks of this Series as a list of Series. + + Examples + -------- + >>> s1 = pl.Series("a", [1, 2, 3]) + >>> s2 = pl.Series("a", [4, 5, 6]) + >>> s = pl.concat([s1, s2], rechunk = False) + >>> s.get_chunks() + [shape: (3,) + Series: 'a' [i64] + [ + 1 + 2 + 3 + ], shape: (3,) + Series: 'a' [i64] + [ + 4 + 5 + 6 + ]] + """ return self._s.get_chunks() def implode(self) -> Self: From 8b024031e9dc39e5993c8d3d846cb0b4af2a6150 Mon Sep 17 00:00:00 2001 From: tharunsuresh-code Date: Sat, 11 May 2024 19:53:14 -0700 Subject: [PATCH 2/4] fixed blank space issue --- py-polars/polars/series/series.py | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/py-polars/polars/series/series.py b/py-polars/polars/series/series.py index 16c223a917e3..e3b5132a6b81 100644 --- a/py-polars/polars/series/series.py +++ b/py-polars/polars/series/series.py @@ -3315,7 +3315,7 @@ def limit(self, n: int = 10) -> Series: See Also -------- head - + Examples -------- >>> s = pl.Series("a", [1, 2, 3, 4, 5]) @@ -3327,9 +3327,9 @@ def limit(self, n: int = 10) -> Series: 2 3 ] - + Pass a negative value to get all rows `except` the last `abs(n)`. - + >>> s.limit(-3) shape: (2,) Series: 'a' [i64] @@ -4090,7 +4090,7 @@ def explode(self) -> Series: Examples -------- - >>> s = pl.Series("a", [[1, 2, 3], [4,5,6]]) + >>> s = pl.Series("a", [[1, 2, 3], [4, 5, 6]]) >>> s shape: (2,) Series: 'a' [list[i64]] @@ -7340,7 +7340,7 @@ def new_from_index(self, index: int, length: int) -> Self: Examples -------- >>> s = pl.Series("a", [1, 2, 3, 4, 5]) - >>> s.new_from_index(1,3) + >>> s.new_from_index(1, 3) shape: (3,) Series: 'a' [i64] [ @@ -7393,7 +7393,7 @@ def get_chunks(self) -> list[Series]: -------- >>> s1 = pl.Series("a", [1, 2, 3]) >>> s2 = pl.Series("a", [4, 5, 6]) - >>> s = pl.concat([s1, s2], rechunk = False) + >>> s = pl.concat([s1, s2], rechunk=False) >>> s.get_chunks() [shape: (3,) Series: 'a' [i64] From 9d0f83fd467c46ca4010773a36d64f6729455694 Mon Sep 17 00:00:00 2001 From: tharunsuresh-code Date: Sun, 12 May 2024 10:26:01 -0700 Subject: [PATCH 3/4] changed reinterpret doc example to a relevant one --- py-polars/polars/series/series.py | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/py-polars/polars/series/series.py b/py-polars/polars/series/series.py index e3b5132a6b81..ac6b7d27905b 100644 --- a/py-polars/polars/series/series.py +++ b/py-polars/polars/series/series.py @@ -6349,21 +6349,21 @@ def reinterpret(self, *, signed: bool = True) -> Series: Examples -------- - >>> s = pl.Series("a", [1, 2, 3]) + >>> s = pl.Series("a", [-2**60, -2, 3]) >>> s shape: (3,) Series: 'a' [i64] [ - 1 - 2 + -1152921504606846976 + -2 3 ] >>> s.reinterpret(signed=False) shape: (3,) Series: 'a' [u64] [ - 1 - 2 + 17293822569102704640 + 18446744073709551614 3 ] """ From 3048a136d77c6b5149166a2dedcc9f3ec2c95bdb Mon Sep 17 00:00:00 2001 From: tharunsuresh-code Date: Sun, 12 May 2024 10:30:55 -0700 Subject: [PATCH 4/4] adjusted fmt --- py-polars/polars/series/series.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/py-polars/polars/series/series.py b/py-polars/polars/series/series.py index ac6b7d27905b..74576a15a8c1 100644 --- a/py-polars/polars/series/series.py +++ b/py-polars/polars/series/series.py @@ -6349,7 +6349,7 @@ def reinterpret(self, *, signed: bool = True) -> Series: Examples -------- - >>> s = pl.Series("a", [-2**60, -2, 3]) + >>> s = pl.Series("a", [-(2**60), -2, 3]) >>> s shape: (3,) Series: 'a' [i64]