From c11ea66bf91d5cb89a5076399f637a292ba2e079 Mon Sep 17 00:00:00 2001
From: MarcoGorelli <33491632+MarcoGorelli@users.noreply.github.com>
Date: Tue, 22 Aug 2023 17:36:19 +0100
Subject: [PATCH 1/2] add sort

---
 .../dataframe_api/column_object.py            | 29 +++++++++++++
 .../dataframe_api/dataframe_object.py         | 41 +++++++++++++++++++
 2 files changed, 70 insertions(+)

diff --git a/spec/API_specification/dataframe_api/column_object.py b/spec/API_specification/dataframe_api/column_object.py
index dab7328f..4a53a556 100644
--- a/spec/API_specification/dataframe_api/column_object.py
+++ b/spec/API_specification/dataframe_api/column_object.py
@@ -141,6 +141,35 @@ def get_value(self, row_number: int) -> Scalar:
         """
         ...
 
+    def sort(
+        self,
+        *,
+        ascending: bool = True,
+        nulls_position: Literal['first', 'last'] = 'last',
+    ) -> Column[DType]:
+        """
+        Sort column.
+
+        If you need the indices which would sort the column,
+        use :meth:`sorted_indices`.
+
+        Parameters
+        ----------
+        ascending : bool
+            If `True`, sort in ascending order.
+            If `False`, sort in descending order.
+        nulls_position : ``{'first', 'last'}``
+            Whether null values should be placed at the beginning
+            or at the end of the result.
+            Note that the position of NaNs is unspecified and may
+            vary based on the implementation.
+
+        Returns
+        -------
+        Column
+        """
+        ...
+
     def sorted_indices(
         self,
         *,
diff --git a/spec/API_specification/dataframe_api/dataframe_object.py b/spec/API_specification/dataframe_api/dataframe_object.py
index b0f70b43..9af87432 100644
--- a/spec/API_specification/dataframe_api/dataframe_object.py
+++ b/spec/API_specification/dataframe_api/dataframe_object.py
@@ -244,6 +244,47 @@ def get_column_names(self) -> Sequence[str]:
         Sequence[str]
         """
         ...
+    
+    def sort(
+        self,
+        keys: Sequence[str] | None = None,
+        *,
+        ascending: Sequence[bool] | bool = True,
+        nulls_position: Literal['first', 'last'] = 'last',
+    ) -> DataFrame:
+        """
+        Sort dataframe according to given columns.
+
+        If you only need the indices which would sort the dataframe, use
+        :meth:`sorted_indices`.
+
+        Parameters
+        ----------
+        keys : Sequence[str] | None
+            Names of columns to sort by.
+            If `None`, sort by all columns.
+        ascending : Sequence[bool] or bool
+            If `True`, sort by all keys in ascending order.
+            If `False`, sort by all keys in descending order.
+            If a sequence, it must be the same length as `keys`,
+            and determines the direction with which to use each
+            key to sort by.
+        nulls_position : ``{'first', 'last'}``
+            Whether null values should be placed at the beginning
+            or at the end of the result.
+            Note that the position of NaNs is unspecified and may
+            vary based on the implementation.
+
+        Returns
+        -------
+        DataFrame
+    
+        Raises
+        ------
+        ValueError
+            If `keys` and `ascending` are sequences of different lengths.
+        """
+        ...
 
     def sorted_indices(
         self,

From 542f7499a34908d5c67a0a8cd18195ce0dc1ce55 Mon Sep 17 00:00:00 2001
From: MarcoGorelli <33491632+MarcoGorelli@users.noreply.github.com>
Date: Thu, 24 Aug 2023 09:31:07 +0100
Subject: [PATCH 2/2] update sorted_indices docs

---
 spec/API_specification/dataframe_api/column_object.py    | 4 +---
 spec/API_specification/dataframe_api/dataframe_object.py | 4 +---
 2 files changed, 2 insertions(+), 6 deletions(-)

diff --git a/spec/API_specification/dataframe_api/column_object.py b/spec/API_specification/dataframe_api/column_object.py
index 4a53a556..c8eb666f 100644
--- a/spec/API_specification/dataframe_api/column_object.py
+++ b/spec/API_specification/dataframe_api/column_object.py
@@ -179,9 +179,7 @@ def sorted_indices(
         """
         Return row numbers which would sort column.
 
-        If you need to sort the Column, you can simply do::
-
-            col.get_rows(col.sorted_indices())
+        If you need to sort the Column, use :meth:`sort`.
 
         Parameters
         ----------
diff --git a/spec/API_specification/dataframe_api/dataframe_object.py b/spec/API_specification/dataframe_api/dataframe_object.py
index 9af87432..cd109a7e 100644
--- a/spec/API_specification/dataframe_api/dataframe_object.py
+++ b/spec/API_specification/dataframe_api/dataframe_object.py
@@ -296,9 +296,7 @@ def sorted_indices(
         """
         Return row numbers which would sort according to given columns.
 
-        If you need to sort the DataFrame, you can simply do::
-
-            df.get_rows(df.sorted_indices(keys))
+        If you need to sort the DataFrame, use :meth:`sort`.
 
         Parameters
         ----------