[GitHub] [arrow] jorisvandenbossche commented on a diff in pull request #35865: GH-35740: Add documentation for list arrays' values property

["jorisvandenbossche (via GitHub)" <gi...@apache.org>]

jorisvandenbossche commented on code in PR #35865:
URL: https://github.com/apache/arrow/pull/35865#discussion_r1219235011


##########
python/pyarrow/array.pxi:
##########
@@ -2053,6 +2053,38 @@ cdef class ListArray(BaseListArray):
 
     @property
     def values(self):
+        """
+        Return the underlying array of values which backs the ListArray.
+
+        This is logically a concatenation of all the sub-lists in this array.
+
+        Note even null values are included. If any of the list slots
+        are null, but are backed by a non-empty sub-list, those values
+        will be included in the output.
+
+        Compare with ``flatten``, which returns only the non-null
+        values.
+
+        Returns
+        -------
+        values : Array
+

Review Comment:
   ```suggestion
   
   See Also
   --------
   ListArray.flatten : ...
   
   ```



##########
python/pyarrow/array.pxi:
##########
@@ -2053,6 +2053,38 @@ cdef class ListArray(BaseListArray):
 
     @property
     def values(self):
+        """
+        Return the underlying array of values which backs the ListArray.
+
+        This is logically a concatenation of all the sub-lists in this array.
+
+        Note even null values are included. If any of the list slots
+        are null, but are backed by a non-empty sub-list, those values
+        will be included in the output.
+
+        Compare with ``flatten``, which returns only the non-null

Review Comment:
   ```suggestion
           Compare with :meth:`flatten`, which returns only the non-null
   ```
   
   (the the online docs will link to it)



##########
python/pyarrow/array.pxi:
##########
@@ -2053,6 +2053,38 @@ cdef class ListArray(BaseListArray):
 
     @property
     def values(self):
+        """
+        Return the underlying array of values which backs the ListArray.
+
+        This is logically a concatenation of all the sub-lists in this array.

Review Comment:
   This is the same sentence as we have in the flatten docstring. But given the difference between both, it maybe make sense to not have that sentence here? (strictly speaking, it is more than the "logical" concatenation of the sub-lists, given the nulls can be included and the offset is being ignored)



##########
python/pyarrow/array.pxi:
##########
@@ -2053,6 +2053,38 @@ cdef class ListArray(BaseListArray):
 
     @property
     def values(self):
+        """
+        Return the underlying array of values which backs the ListArray.
+
+        This is logically a concatenation of all the sub-lists in this array.
+
+        Note even null values are included. If any of the list slots
+        are null, but are backed by a non-empty sub-list, those values
+        will be included in the output.
+
+        Compare with ``flatten``, which returns only the non-null
+        values.
+
+        Returns
+        -------
+        values : Array
+
+        Examples
+        --------
+        >>> 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
+        ]
+

Review Comment:
   Adding one more example of a sliced array might illustrate the difference between `values` and `.flatten()`



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org