wjones127 commented on code in PR #35453:
URL: https://github.com/apache/arrow/pull/35453#discussion_r1252391999
##########
python/pyarrow/_parquet.pyx:
##########
@@ -494,6 +495,212 @@ cdef class ColumnChunkMetaData(_Weakrefable):
return self.metadata.total_uncompressed_size()
+cdef class SortingColumn:
+ """
+ Sorting specification for a single column.
+
+ Returned by :meth:`RowGroupMetaData.sorting_columns` and used in
+ :class:`ParquetWriter` to specify the sort order of the data.
+
+ Parameters
+ ----------
+ column_index : int
+ Index of column data is sorted by.
+ descending : bool, default False
+ Whether column is sorted in descending order.
+ nulls_first : bool, default False
+ Whether null values appear before valid values.
+
+ Notes
+ -----
+
+ Column indices are zero-based, refer only to leaf fields, and are in
+ depth-first order. This may make the column indices for nested schemas
+ different from what you expect. In most cases, it will be easier to
+ specify the sort order using column names instead of column indices
+ and converting using the ``from_sort_order`` method.
+
+ Examples
+ --------
+
+ In other APIs, sort order is specified by names, such as:
+
+ >>> sort_order = [('id', 'ascending'), ('timestamp', 'descending')]
+
+ For Parquet, the column index must be used instead:
+
+ >>> import pyarrow.parquet as pq
+ >>> [pq.SortingColumn(0), pq.SortingColumn(1, descending=True)]
+ [SortingColumn(column_index=0, descending=False, nulls_first=False),
SortingColumn(column_index=1, descending=True, nulls_first=False)]
+
+ Convert the sort_order into the list of sorting columns with
+ ``from_sort_order`` (note that the schema must be provided as well):
+
+ >>> import pyarrow as pa
+ >>> schema = pa.schema([('id', pa.int64()), ('timestamp',
pa.timestamp('ms'))])
+ >>> sorting_columns = pq.SortingColumn.from_sort_order(schema, sort_order)
+ >>> sorting_columns
+ (SortingColumn(column_index=0, descending=False, nulls_first=False),
SortingColumn(column_index=1, descending=True, nulls_first=False))
+
+ Convert back to the sort order with ``to_sort_order``:
+
+ >>> pq.SortingColumn.to_sort_order(schema, sorting_columns)
+ ((('id', 'ascending'), ('timestamp', 'descending')), 'at_end')
+
+ See Also
+ --------
+ RowGroupMetaData.sorting_columns
+ """
+ cdef int column_index
+ cdef c_bool descending
+ cdef c_bool nulls_first
+
+ def __init__(self, int column_index, c_bool descending=False, c_bool
nulls_first=False):
+ self.column_index = column_index
+ self.descending = descending
+ self.nulls_first = nulls_first
+
+ @classmethod
+ def from_sort_order(cls, Schema schema, sort_keys,
null_placement='at_end'):
+ """
+ Create a tuple of SortingColumn objects from the same arguments as
+ :class:`pyarrow.compute.SortOptions`.
+
+ Parameters
+ ----------
+ schema : Schema
+ Schema of the input data.
+ sort_keys : Sequence of (name, order) tuples
+ Names of field/column keys (str) to sort the input on,
+ along with the order each field/column is sorted in.
+ Accepted values for `order` are "ascending", "descending".
+ null_placement : {'at_start', 'at_end'}, default 'at_end'
+ Where null values should appear in the sort order.
+
+ Returns
+ -------
+ sorting_columns : tuple of SortingColumn
+ """
+ if null_placement == 'at_start':
+ nulls_first = True
+ elif null_placement == 'at_end':
+ nulls_first = False
+ else:
+ raise ValueError('null_placement must be "at_start" or "at_end"')
+
+ col_map = _name_to_index_map(schema)
+
+ sorting_columns = []
+
+ for sort_key in sort_keys:
+ if isinstance(sort_key, str):
+ name = sort_key
+ descending = False
+ elif (isinstance(sort_key, tuple) and len(sort_key) == 2 and
+ isinstance(sort_key[0], str) and
+ isinstance(sort_key[1], str)):
+ name, descending = sort_key
+ if descending == "descending":
+ descending = True
+ elif descending == "ascending":
+ descending = False
+ else:
+ raise ValueError("Invalid sort key direction: {0}"
+ .format(descending))
+ else:
+ raise ValueError("Invalid sort key: {0}".format(sort_key))
+
+ try:
+ column_index = col_map[name]
+ except KeyError:
+ raise ValueError("Sort key name '{0}' not found in
schema:\n{1}"
+ .format(name, schema))
+
+ sorting_columns.append(
+ cls(column_index, descending=descending,
nulls_first=nulls_first)
+ )
+
+ return tuple(sorting_columns)
+
+ @staticmethod
+ def to_sort_order(Schema schema, sorting_columns):
+ """
+ Convert a tuple of SortingColumn objects to the same format as
+ :class:`pyarrow.compute.SortOptions`.
+
+ Parameters
+ ----------
+ schema : Schema
+ Schema of the input data.
+ sorting_columns : tuple of SortingColumn
+ Columns to sort the input on.
+
+ Returns
+ -------
+ sort_keys : tuple of (name, order) tuples
+ null_placement : {'at_start', 'at_end'}
Review Comment:
Yeah it's part of numpydoc style:
https://numpydoc.readthedocs.io/en/latest/format.html#parameters
--
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: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
