This is an automated email from the ASF dual-hosted git repository.
alenka pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/arrow.git
The following commit(s) were added to refs/heads/main by this push:
new 6837d05951 GH-35740: Add documentation for list arrays' values
property (#35865)
6837d05951 is described below
commit 6837d0595153b3a20b9a9fa63d4149115a1987c2
Author: Spencer Nelson <[email protected]>
AuthorDate: Wed Aug 23 11:13:33 2023 -0700
GH-35740: Add documentation for list arrays' values property (#35865)
Just docs.
I'm a little shaky on my understanding of exactly what's going on with
FixedSizeListArray.values, and its behavior with nulls, so that wording might
deserve a careful read.
* Closes: #35740
Lead-authored-by: Spencer Nelson <[email protected]>
Co-authored-by: Joris Van den Bossche <[email protected]>
Co-authored-by: Alenka Frim <[email protected]>
Signed-off-by: AlenkaF <[email protected]>
---
python/pyarrow/array.pxi | 172 ++++++++++++++++++++++++++++++++++++++++++++++-
1 file changed, 171 insertions(+), 1 deletion(-)
diff --git a/python/pyarrow/array.pxi b/python/pyarrow/array.pxi
index ce4eafd8e3..e26b1ad329 100644
--- a/python/pyarrow/array.pxi
+++ b/python/pyarrow/array.pxi
@@ -1964,7 +1964,7 @@ cdef class BaseListArray(Array):
The returned Array is logically a concatenation of all the sub-lists
in this Array.
- Note that this method is different from ``self.values()`` in that
+ Note that this method is different from ``self.values`` in that
it takes care of the slicing offset as well as null elements backed
by non-empty sub-lists.
@@ -2103,6 +2103,72 @@ cdef class ListArray(BaseListArray):
@property
def values(self):
+ """
+ Return the underlying array of values which backs the ListArray
+ ignoring the array's offset.
+
+ If any of the list elements are null, but are backed by a
+ non-empty sub-list, those elements will be included in the
+ output.
+
+ Compare with :meth:`flatten`, which returns only the non-null
+ values taking into consideration the array's offset.
+
+ Returns
+ -------
+ values : Array
+
+ See Also
+ --------
+ ListArray.flatten : ...
+
+ Examples
+ --------
+
+ The values include null elements from sub-lists:
+
+ >>> import pyarrow as pa
+ >>> array = pa.array([[1, 2], None, [3, 4, None, 6]])
+ >>> array.values
+ <pyarrow.lib.Int64Array object at ...>
+ [
+ 1,
+ 2,
+ 3,
+ 4,
+ null,
+ 6
+ ]
+
+ If an array is sliced, the slice still uses the same
+ underlying data as the original array, just with an
+ offset. Since values ignores the offset, the values are the
+ same:
+
+ >>> sliced = array.slice(1, 2)
+ >>> sliced
+ <pyarrow.lib.ListArray object at ...>
+ [
+ null,
+ [
+ 3,
+ 4,
+ null,
+ 6
+ ]
+ ]
+ >>> sliced.values
+ <pyarrow.lib.Int64Array object at ...>
+ [
+ 1,
+ 2,
+ 3,
+ 4,
+ null,
+ 6
+ ]
+
+ """
cdef CListArray* arr = <CListArray*> self.ap
return pyarrow_wrap_array(arr.values())
@@ -2190,6 +2256,74 @@ cdef class LargeListArray(BaseListArray):
@property
def values(self):
+ """
+ Return the underlying array of values which backs the LargeListArray
+ ignoring the array's offset.
+
+ If any of the list elements are null, but are backed by a
+ non-empty sub-list, those elements will be included in the
+ output.
+
+ Compare with :meth:`flatten`, which returns only the non-null
+ values taking into consideration the array's offset.
+
+ Returns
+ -------
+ values : Array
+
+ See Also
+ --------
+ LargeListArray.flatten : ...
+
+ Examples
+ --------
+
+ The values include null elements from the sub-lists:
+
+ >>> import pyarrow as pa
+ >>> array = pa.array(
+ ... [[1, 2], None, [3, 4, None, 6]],
+ ... type=pa.large_list(pa.int32()),
+ ... )
+ >>> array.values
+ <pyarrow.lib.Int32Array object at ...>
+ [
+ 1,
+ 2,
+ 3,
+ 4,
+ null,
+ 6
+ ]
+
+ If an array is sliced, the slice still uses the same
+ underlying data as the original array, just with an
+ offset. Since values ignores the offset, the values are the
+ same:
+
+ >>> sliced = array.slice(1, 2)
+ >>> sliced
+ <pyarrow.lib.LargeListArray object at ...>
+ [
+ null,
+ [
+ 3,
+ 4,
+ null,
+ 6
+ ]
+ ]
+ >>> sliced.values
+ <pyarrow.lib.Int32Array object at ...>
+ [
+ 1,
+ 2,
+ 3,
+ 4,
+ null,
+ 6
+ ]
+ """
cdef CLargeListArray* arr = <CLargeListArray*> self.ap
return pyarrow_wrap_array(arr.values())
@@ -2346,6 +2480,42 @@ cdef class FixedSizeListArray(BaseListArray):
@property
def values(self):
+ """
+ Return the underlying array of values which backs the
+ FixedSizeListArray.
+
+ Note even null elements are included.
+
+ Compare with :meth:`flatten`, which returns only the non-null
+ sub-list values.
+
+ Returns
+ -------
+ values : Array
+
+ See Also
+ --------
+ FixedSizeListArray.flatten : ...
+
+ Examples
+ --------
+ >>> import pyarrow as pa
+ >>> array = pa.array(
+ ... [[1, 2], None, [3, None]],
+ ... type=pa.list_(pa.int32(), 2)
+ ... )
+ >>> array.values
+ <pyarrow.lib.Int32Array object at ...>
+ [
+ 1,
+ 2,
+ null,
+ null,
+ 3,
+ null
+ ]
+
+ """
cdef CFixedSizeListArray* arr = <CFixedSizeListArray*> self.ap
return pyarrow_wrap_array(arr.values())
