h"jSSKJr SSKJr SSKJrJrJr SSKJ r SSK J r SSK Jr \(a SSKJr SSKJrJr SS KJr SS KJrJrJrJr \"S S 55rg )) annotations)Sequence) TYPE_CHECKINGAnyCallable) functions)wrap_s) expr_dispatch) Collection)ExprSeries)PySeries)IntoExprIntoExprColumnListToStructWidthStrategy NullBehaviorc\rSrSrSrSrS:SjrS;SjrS;SjrS;Sjr S;Sjr SS?SjjrS>S?SjjrS S SS.S@SjjrS;SjrS S.SASjjrS;SjrSBSjrS S.SCSjjrS S.SDSjjrSESFSjjrSGS jrSS!.SHS"jjrS;S#jrS;S$jrSS%.SIS&jjrS;S'jr S;S(jr!SJSKS)jjr"S>SLS*jjr#S>> s = pl.Series( ... [[True, True], [False, True], [False, False], [None], [], None], ... dtype=pl.List(pl.Boolean), ... ) >>> s.list.all() shape: (6,) Series: '' [bool] [ true false false true true null ] Nrs rallListNameSpace.all r cg)a Evaluate whether any boolean value in a list is true. Returns ------- Series Series of data type :class:`Boolean`. Notes ----- If there are no non-null elements in a row, the output is `False`. Examples -------- >>> s = pl.Series( ... [[True, True], [False, True], [False, False], [None], [], None], ... dtype=pl.List(pl.Boolean), ... ) >>> s.list.any() shape: (6,) Series: '' [bool] [ true true false false false null ] Nr"r#s ranyListNameSpace.any@r&r cg)a  Return the number of elements in each list. Null values count towards the total. Returns ------- Series Series of data type :class:`UInt32`. Examples -------- >>> s = pl.Series([[1, 2, None], [5]]) >>> s.list.len() shape: (2,) Series: '' [u32] [ 3 1 ] Nr"r#s rlenListNameSpace.len`r&r cg)a Drop all null values in the list. The original order of the remaining elements is preserved. Examples -------- >>> s = pl.Series("values", [[None, 1, None, 2], [None], [3, 4]]) >>> s.list.drop_nulls() shape: (3,) Series: 'values' [list[i64]] [ [1, 2] [] [3, 4] ] Nr"r#s r drop_nullsListNameSpace.drop_nullswr&r NF)fractionwith_replacementshuffleseedcg)a Sample from this list. Parameters ---------- n Number of items to return. Cannot be used with `fraction`. Defaults to 1 if `fraction` is None. fraction Fraction of items to return. Cannot be used with `n`. with_replacement Allow values to be sampled more than once. shuffle Shuffle the order of sampled data points. seed Seed for the random number generator. If set to None (default), a random seed is generated for each sample operation. Examples -------- >>> s = pl.Series("values", [[1, 2, 3], [4, 5]]) >>> s.list.sample(n=pl.Series("n", [2, 1]), seed=1) shape: (2,) Series: 'values' [list[i64]] [ [2, 3] [5] ] Nr")rnr0r1r2r3s rsampleListNameSpace.sampler&r cg)z Sum all the arrays in the list. Notes ----- If there are no non-null elements in a row, the output is `0`. Examples -------- >>> s = pl.Series("values", [[1], [2, 3]]) >>> s.list.sum() shape: (2,) Series: 'values' [i64] [ 1 5 ] Nr"r#s rsumListNameSpace.sumr&r cg)z 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 ] Nr"r#s rmaxListNameSpace.maxr&r cg)z 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 ] Nr"r#s rminListNameSpace.minr&r cg)z 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 ] Nr"r#s rmeanListNameSpace.meanr&r cg)z Compute the median value of the arrays in the list. Examples -------- >>> s = pl.Series("values", [[-1, 0, 1], [1, 10]]) >>> s.list.median() shape: (2,) Series: 'values' [f64] [ 0.0 5.5 ] Nr"r#s rmedianListNameSpace.medianr&r cg)z Compute the std value of the arrays in the list. Examples -------- >>> s = pl.Series("values", [[-1, 0, 1], [1, 10]]) >>> s.list.std() shape: (2,) Series: 'values' [f64] [ 1.0 6.363961 ] Nr"rddofs rstdListNameSpace.stdr&r cg)z Compute the var value of the arrays in the list. Examples -------- >>> s = pl.Series("values", [[-1, 0, 1], [1, 10]]) >>> s.list.var() shape: (2,) Series: 'values' [f64] [ 1.0 40.5 ] Nr"rHs rvarListNameSpace.varr&r T) descending nulls_last multithreadedcg)a Sort the arrays in this column. Parameters ---------- descending Sort in descending order. nulls_last Place null values last. multithreaded Sort using multiple threads. Examples -------- >>> s = pl.Series("a", [[3, 2, 1], [9, 1, 2]]) >>> s.list.sort() shape: (2,) Series: 'a' [list[i64]] [ [1, 2, 3] [1, 2, 9] ] >>> s.list.sort(descending=True) shape: (2,) Series: 'a' [list[i64]] [ [3, 2, 1] [9, 2, 1] ] Nr")rrOrPrQs rsortListNameSpace.sort%r&r cg)z 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] ] Nr"r#s rreverseListNameSpace.reverseKr&r )maintain_ordercg)a Get the unique/distinct values in the list. Parameters ---------- 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] ] Nr")rrXs runiqueListNameSpace.unique[r&r cg)z Count the number of unique values in every sub-lists. Examples -------- >>> s = pl.Series("a", [[1, 1, 2], [2, 3, 4]]) >>> s.list.n_unique() shape: (2,) Series: 'a' [u32] [ 2 3 ] Nr"r#s rn_uniqueListNameSpace.n_uniquepr&r cg)aV Concat the arrays in a Series dtype List in linear time. Parameters ---------- 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] ] Nr"rothers rconcatListNameSpace.concatr&r ) null_on_oobcg)a! Get the value by index in the sublists. So index `0` would return the first item of every sublist and index `-1` would return the last item of every sublist if an index is out of bounds, it will return a `None`. Parameters ---------- index Index to return per sublist null_on_oob Behavior if an index is out of bounds: * True -> set as null * False -> raise an error Examples -------- >>> s = pl.Series("a", [[3, 2, 1], [], [1, 2]]) >>> s.list.get(0, null_on_oob=True) shape: (3,) Series: 'a' [i64] [ 3 null 1 ] Nr")rindexrds rgetListNameSpace.getr&r cg)a0 Take sublists by multiple indices. The indices may be defined in a single column, or by sublists in another column of dtype `List`. Parameters ---------- indices Indices to return per sublist null_on_oob Behavior if an index is out of bounds: 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] ] Nr")rindicesrds rgatherListNameSpace.gatherr&r cg)a9 Take every n-th value start from offset in sublists. Parameters ---------- n Gather every n-th element. offset Starting index. Examples -------- >>> s = pl.Series("a", [[1, 2, 3], [], [6, 7, 8, 9]]) >>> s.list.gather_every(2, offset=1) shape: (3,) Series: 'a' [list[i64]] [ [2] [] [7, 9] ] Nr")rr5offsets r gather_everyListNameSpace.gather_everyr&r c$URU5$r)rg)ritems r __getitem__ListNameSpace.__getitem__sxx~r ) ignore_nullscg)aZ Join all string items in a sublist and place a separator between them. This errors if inner type of list `!= String`. Parameters ---------- separator string to separate the items with ignore_nulls Ignore null values (default). If set to ``False``, null values will be propagated. If the sub-list contains any null values, the output is ``None``. Returns ------- Series Series of data type :class:`String`. Examples -------- >>> s = pl.Series([["foo", "bar"], ["hello", "world"]]) >>> s.list.join(separator="-") shape: (2,) Series: '' [str] [ "foo-bar" "hello-world" ] Nr")r separatorrus rjoinListNameSpace.joinr&r cg)z 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 ] Nr"r#s rfirstListNameSpace.firstr&r cg)z 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 ] Nr"r#s rlastListNameSpace.last,r&r ) nulls_equalcg)a Check if sublists contain the given item. Parameters ---------- item Item that will be checked for membership nulls_equal : bool, default True If True, treat null as a distinct value. Null values will not propagate. Returns ------- 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 ] Nr")rrrrs rcontainsListNameSpace.contains=r&r cg)a- Retrieve the index of the minimal value in every sublist. Returns ------- 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 ] Nr"r#s rarg_minListNameSpace.arg_minZr&r cg)a- Retrieve the index of the maximum value in every sublist. Returns ------- 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 ] Nr"r#s rarg_maxListNameSpace.arg_maxpr&r cg)uE Calculate the first discrete difference between shifted items of every sublist. Parameters ---------- n Number of slots to shift. null_behavior : {'ignore', 'drop'} How to handle null values. Examples -------- >>> s = pl.Series("a", [[1, 2, 3, 4], [10, 2, 1]]) >>> s.list.diff() shape: (2,) Series: 'a' [list[i64]] [ [null, 1, … 1] [null, -8, -1] ] >>> s.list.diff(n=2) shape: (2,) Series: 'a' [list[i64]] [ [null, null, … 2] [null, null, -9] ] >>> s.list.diff(n=2, null_behavior="drop") shape: (2,) Series: 'a' [list[i64]] [ [2, 2] [-9] ] Nr")rr5 null_behaviors rdiffListNameSpace.diffr&r cg)a Shift list values by the given number of indices. Parameters ---------- n Number of indices to shift forward. If a negative value is passed, values are shifted in the opposite direction instead. Notes ----- This method is similar to the `LAG` operation in SQL when the value for `n` is positive. With a negative value for `n`, it is similar to `LEAD`. Examples -------- By default, list values are shifted forward by one index. >>> s = pl.Series([[1, 2, 3], [4, 5]]) >>> s.list.shift() shape: (2,) Series: '' [list[i64]] [ [null, 1, 2] [null, 4] ] Pass a negative value to shift in the opposite direction instead. >>> s.list.shift(-2) shape: (2,) Series: '' [list[i64]] [ [3, null, null] [null, null] ] Nr"rr5s rshiftListNameSpace.shiftr&r cg)ak Slice every sublist. Parameters ---------- offset Start index. Negative indexing is supported. length Length of the slice. If set to `None` (default), the slice is taken to the end of the list. Examples -------- >>> s = pl.Series("a", [[1, 2, 3, 4], [10, 2, 1]]) >>> s.list.slice(1, 2) shape: (2,) Series: 'a' [list[i64]] [ [2, 3] [2, 1] ] Nr")rrnlengths rsliceListNameSpace.slicer&r cg)a Slice the first `n` values of every sublist. Parameters ---------- n Number of values to return for each sublist. Examples -------- >>> s = pl.Series("a", [[1, 2, 3, 4], [10, 2, 1]]) >>> s.list.head(2) shape: (2,) Series: 'a' [list[i64]] [ [1, 2] [10, 2] ] Nr"rs rheadListNameSpace.headr&r cg)a Slice the last `n` values of every sublist. Parameters ---------- n Number of values to return for each sublist. Examples -------- >>> s = pl.Series("a", [[1, 2, 3, 4], [10, 2, 1]]) >>> s.list.tail(2) shape: (2,) Series: 'a' [list[i64]] [ [3, 4] [2, 1] ] Nr"rs rtailListNameSpace.tailr&r cg)a Returns a column with a separate row for every list element. Returns ------- Series Series with the data type of the list elements. See Also -------- Series.reshape : Reshape this Series to a flat Series or a Series of Lists. Examples -------- >>> s = pl.Series("a", [[1, 2, 3], [4, 5, 6]]) >>> s.list.explode() shape: (6,) Series: 'a' [i64] [ 1 2 3 4 5 6 ] Nr"r#s rexplodeListNameSpace.exploder&r cg)a: Count how often the value produced by `element` occurs. Parameters ---------- 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 ] Nr")relements r count_matchesListNameSpace.count_matches3r&r cg)a Convert a List column into an Array column with the same inner data type. Parameters ---------- width Width of the resulting Array column. Returns ------- Series Series of data type :class:`Array`. Examples -------- >>> s = pl.Series([[1, 2], [3, 4]], dtype=pl.List(pl.Int8)) >>> s.list.to_array(2) shape: (2,) Series: '' [array[i8, 2]] [ [1, 2] [3, 4] ] Nr")rwidths rto_arrayListNameSpace.to_arrayKr&r cb[U[5(aw[UR5nUR 5R [ R"UR5RRUS95R5$[URRX55$)uo Convert the series of type `List` to a series of type `Struct`. Parameters ---------- n_field_strategy : {'first_non_null', 'max_width'} Strategy to determine the number of fields of the struct. * "first_non_null": set number of fields equal to the length of the first non zero-length sublist. * "max_width": set number of fields as max length of all sublists. fields If the name and number of the desired fields is known in advance a list of field names can be given, which will be assigned by index. Otherwise, to dynamically assign field names, a custom function can be used; if neither are set, fields will be `field_0, field_1 .. field_n`. Examples -------- Convert list to struct with default field name assignment: >>> s1 = pl.Series("n", [[0, 1, 2], [0, 1]]) >>> s2 = s1.list.to_struct() >>> s2 shape: (2,) Series: 'n' [struct[3]] [ {0,1,2} {0,1,null} ] >>> s2.struct.fields ['field_0', 'field_1', 'field_2'] Convert list to struct with field name assignment by function/index: >>> s3 = s1.list.to_struct(fields=lambda idx: f"n{idx:02}") >>> s3.struct.fields ['n00', 'n01', 'n02'] Convert list to struct with field name assignment by index from a list of names: >>> s1.list.to_struct(fields=["one", "two", "three"]).struct.unnest() shape: (2, 3) ┌─────┬─────┬───────┐ │ one ┆ two ┆ three │ │ --- ┆ --- ┆ --- │ │ i64 ┆ i64 ┆ i64 │ ╞═════╪═════╪═══════╡ │ 0 ┆ 1 ┆ 2 │ │ 0 ┆ 1 ┆ null │ └─────┴─────┴───────┘ )fields) isinstancerr rto_frame select_seqFcolnamer to_struct to_serieslist_to_struct)rn_field_strategyrss rrListNameSpace.to_structes{r fh ' 'twwA AEE!&&M..888GH  dgg,,-=FGGr )parallelcg)ao Run any polars expression against the lists' elements. Parameters ---------- expr Expression to run. Note that you can select an element with `pl.first()`, or `pl.col()` parallel Run all expression parallel. Don't activate this blindly. Parallelism is worth it if there is enough work to do per thread. This likely should not be use in the group by context, because we already parallel execution per group Examples -------- >>> 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] ] Nr")rexprrs revalListNameSpace.evalr&r cg)a Filter elements in each list by a boolean expression, returning a new Series of lists. Parameters ---------- predicate A boolean expression evaluated on each list element. Use `pl.element()` to refer to the current element. Examples -------- >>> import polars as pl >>> s = pl.Series("a", [[1, 4], [8, 5], [3, 2]]) >>> s.list.filter(pl.element() % 2 == 0) shape: (3,) Series: 'a' [list[i64]] [ [4] [8] [2] ] Nr")r predicates rfilterListNameSpace.filterr&r cg)a Compute the SET UNION between the elements in this list and the elements of `other`. Parameters ---------- 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_union(b) # doctest: +IGNORE_RESULT shape: (4,) Series: '' [list[i64]] [ [1, 2, 3, 4] [3] [null, 3, 4] [5, 6, 7, 8] ] Nr"r`s r set_unionListNameSpace.set_unionr&r cg)a Compute the SET DIFFERENCE between the elements in this list and the elements of `other`. Parameters ---------- other Right hand side of the set operation. See Also -------- polars.Series.list.diff: Calculates the n-th discrete difference of every sublist. 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_difference(b) shape: (4,) Series: '' [list[i64]] [ [1] [] [] [5, 7] ] Nr"r`s rset_differenceListNameSpace.set_differencer&r cg)a Compute the SET INTERSECTION between the elements in this list and the elements of `other`. Parameters ---------- 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_intersection(b) shape: (4,) Series: '' [list[i64]] [ [2, 3] [] [null, 3] [6] ] Nr"r`s rset_intersectionListNameSpace.set_intersectionr&r cg)a Compute the SET SYMMETRIC DIFFERENCE between the elements in this list and the elements of `other`. Parameters ---------- 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] ] Nr"r`s rset_symmetric_difference&ListNameSpace.set_symmetric_difference)r&r r)rr returnNone)rr r) r5zint | IntoExprColumn | Noner0zfloat | IntoExprColumn | Noner1boolr2rr3z int | Nonerr ))rIintrr )rOrrPrrQrrr )rXrrr )raz!list[Series] | Series | list[Any]rr )rfzint | Series | list[int]rdrrr )rjz$Series | list[int] | list[list[int]]rdrrr )r)r5int | IntoExprColumnrnrrr )rrrrr )rwrrurrr )rrrrrrr )rignore)r5rrrrr )r5rrr )rn int | Exprrzint | Expr | Nonerr ))r5rrr )rrrr )rrrr )first_non_nullN)rrrz+Callable[[int], str] | Sequence[str] | Nonerr )rr rrrr )rr rr )razSeries | Collection[Any]rr )2__name__ __module__ __qualname____firstlineno____doc__ _accessorrr$r(r+r.r6r9r<r?rBrErJrMrSrVrZr]rbrgrkrorsrxr{r~rrrrrrrrrrrrrrrrrr__static_attributes__r"r rrrs-I& @ @ . **.% 37!&% &% 0 %  %  % %  % N (      &! " $ $  $  $  $ L 05 *  4" " '"  "  " P" ! 5!  !  ! HGH % /C  4GK B " "?C : , ,% N% N 0 * * : 0 87G>BAH3AH<AH  AHF49 : 0 0 8 0 r rN) __future__rcollections.abcrtypingrrrpolarsrrpolars._utils.wrapr polars.series.utilsr r r r polars._plrrpolars._typingrrrrrr"r rrsL"$//!%-*#$g g g r