reverted and updated documentation

Author: jacobaustin123

doc/source/user_guide/basics.rst

@@ -1796,9 +1796,16 @@ the key is applied per-level to the levels specified by `level`.
        "b": [1, 2, 3],
        "c": [2, 3, 4]
    }).set_index(list("ab"))
+   s1
+
+.. ipython:: python
+
    s1.sort_index(level="a")
    s1.sort_index(level="a", key=lambda idx: idx.str.lower())
 
+For information on key sorting by value, see :ref:`value sorting 
+<basics.sort_value_key>`.
+
 .. _basics.sort_values:
 
 By values
@@ -1841,6 +1848,9 @@ to apply to the values being sorted.
 .. ipython:: python
 
    s1 = pd.Series(['B', 'a', 'C'])
+
+.. ipython:: python
+
    s1.sort_values()
    s1.sort_values(key=lambda x: x.str.lower())
 
@@ -1852,6 +1862,9 @@ a Series, e.g.
 .. ipython:: python
 
    df = pd.DataFrame({"a": ['B', 'a', 'C'], "b": [1, 2, 3]})
+
+.. ipython:: python
+
    df.sort_values(by='a')
    df.sort_values(by='a', key=lambda col: col.str.lower())
 

doc/source/whatsnew/v1.1.0.rst

@@ -51,6 +51,10 @@ See :ref:`sort_values with keys <basics.sort_value_key>` and :ref:`sort_index wi
 .. ipython:: python
 
    s = pd.Series(['C', 'a', 'B'])
+   s
+
+.. ipython:: python
+
    s.sort_values()
 
 
@@ -69,6 +73,10 @@ When applied to a `DataFrame`, they key is applied per-column to all columns or
 
    df = pd.DataFrame({'a': ['C', 'C', 'a', 'a', 'B', 'B'],
                       'b': [1, 2, 3, 4, 5, 6]})
+   df
+
+.. ipython:: python
+
    df.sort_values(by=['a'], key=lambda col: col.str.lower())
 
 

pandas/core/indexes/datetimelike.py

@@ -175,33 +175,15 @@ def sort_values(self, return_indexer=False, ascending=True, key=None):
         """
         idx = ensure_key_mapped(self, key)
 
+        _as = idx.argsort()
+        if not ascending:
+            _as = _as[::-1]
+        sorted_index = self.take(_as)
+
         if return_indexer:
-            _as = idx.argsort()
-            if not ascending:
-                _as = _as[::-1]
-            sorted_index = self.take(_as)
             return sorted_index, _as
         else:
-            # NB: using asi8 instead of _data matters in numpy 1.18
-            #  because the treatment of NaT has been changed to put NaT last
-            #  instead of first.
-            _as = np.argsort(idx.asi8)
-            sorted_values = self.asi8[_as]
-
-            freq = self.freq
-            if freq is not None and not is_period_dtype(self):
-                if freq.n > 0 and not ascending:
-                    freq = freq * -1
-                elif freq.n < 0 and ascending:
-                    freq = freq * -1
-
-            if not ascending:
-                sorted_values = sorted_values[::-1]
-
-            arr = type(self._data)._simple_new(
-                sorted_values, dtype=self.dtype, freq=freq
-            )
-            return type(self)._simple_new(arr, name=self.name)
+            sorted_index
 
     @Appender(_index_shared_docs["take"] % _index_doc_kwargs)
     def take(self, indices, axis=0, allow_fill=True, fill_value=None, **kwargs):

pandas/core/sorting.py

@@ -382,28 +382,38 @@ def ensure_key_mapped(values, key: Optional[Callable], levels=None):
     levels : Optional[List], if values is a MultiIndex, list of levels to
     apply the key to.
     """
+    from pandas.core.indexes.api import Index
+    
     if not key:
         return values.copy()
 
     if isinstance(values, ABCMultiIndex):
         return ensure_key_mapped_multiindex(values, key, level=levels)
 
-    type_of_values = type(values)
     result = key(values.copy())
     if len(result) != len(values):
         raise ValueError(
-            "User-provided `key` function much not change the shape of the array."
+            "User-provided `key` function must not change the shape of the array."
         )
 
-    if not isinstance(result, type_of_values):  # recover from type error
-        try:
-            result = type_of_values(result)
-        except TypeError:
-            raise TypeError("User-provided `key` function returned an invalid type.")
+    try:
+        if isinstance(values, Index):  # allow a new Index class
+            result = Index(result)
+        else:
+            type_of_values = type(values)
+            result = type_of_values(result)  # try to recover otherwise
+    except TypeError:
+        raise TypeError(
+            "User-provided `key` function returned an invalid type {} \
+            which could not be converted to {}.".format(
+                type(result), type(values)
+            )
+        )
 
     return result
 
 
+
 class _KeyMapper:
     """
     Map compressed group id -> key tuple.

pandas/tests/frame/methods/test_sort_values.py

@@ -630,7 +630,7 @@ def key(col):
         expected = df.iloc[[1, 3, 4, 0, 2, 5]]
         tm.assert_frame_equal(result, expected)
 
-    def test_sort_values_key_nan(self):
+    def test_sort_values_key_string(self):
         df = DataFrame(np.array([["hello", "goodbye"], ["hello", "Hello"]]))
 
         result = df.sort_values(1)
@@ -656,3 +656,25 @@ def test_changes_length_raises(self):
         df = pd.DataFrame({"A": [1, 2, 3]})
         with pytest.raises(ValueError, match="change the shape"):
             df.sort_values("A", key=lambda x: x[:1])
+
+    def test_sort_values_key_axes(self):
+        df = DataFrame({0: ["Hello", "goodbye"], 1: [0, 1]})
+
+        result = df.sort_values(0, key=lambda col: col.str.lower())
+        expected = df[::-1]
+        tm.assert_frame_equal(result, expected)
+
+        result = df.sort_values(1, key=lambda col: -col)
+        expected = df[::-1]
+        tm.assert_frame_equal(result, expected)
+
+    def test_sort_values_key_dict_axis(self):
+        df = DataFrame({0: ["Hello", 0], 1: ["goodbye", 1]})
+
+        result = df.sort_values(0, key=lambda col: col.str.lower(), axis=1)
+        expected = df.loc[:, ::-1]
+        tm.assert_frame_equal(result, expected)
+
+        result = df.sort_values(1, key=lambda col: -col, axis=1)
+        expected = df.loc[:, ::-1]
+        tm.assert_frame_equal(result, expected)

pandas/tests/series/methods/test_sort_index.py

@@ -3,7 +3,7 @@
 import numpy as np
 import pytest
 
-from pandas import IntervalIndex, MultiIndex, Series
+from pandas import DatetimeIndex, IntervalIndex, MultiIndex, Series
 import pandas._testing as tm
 
 
@@ -223,7 +223,66 @@ def test_sort_index_key_int(self):
         result = series.sort_index(key=lambda x: 2 * x)
         tm.assert_series_equal(result, series)
 
+    def test_sort_index_kind_key(self, sort_by_key):
+        # GH #14444 & #13589:  Add support for sort algo choosing
+        series = Series(index=[3, 2, 1, 4, 3], dtype=object)
+        expected_series = Series(index=[1, 2, 3, 3, 4], dtype=object)
+
+        index_sorted_series = series.sort_index(kind="mergesort", key=sort_by_key)
+        tm.assert_series_equal(expected_series, index_sorted_series)
+
+        index_sorted_series = series.sort_index(kind="quicksort", key=sort_by_key)
+        tm.assert_series_equal(expected_series, index_sorted_series)
+
+        index_sorted_series = series.sort_index(kind="heapsort", key=sort_by_key)
+        tm.assert_series_equal(expected_series, index_sorted_series)
+
+    def test_sort_index_kind_neg_key(self):
+        # GH #14444 & #13589:  Add support for sort algo choosing
+        series = Series(index=[3, 2, 1, 4, 3], dtype=object)
+        expected_series = Series(index=[4, 3, 3, 2, 1], dtype=object)
+
+        index_sorted_series = series.sort_index(kind="mergesort", key=lambda x: -x)
+        tm.assert_series_equal(expected_series, index_sorted_series)
+
+        index_sorted_series = series.sort_index(kind="quicksort", key=lambda x: -x)
+        tm.assert_series_equal(expected_series, index_sorted_series)
+
+        index_sorted_series = series.sort_index(kind="heapsort", key=lambda x: -x)
+        tm.assert_series_equal(expected_series, index_sorted_series)
+
+    def test_sort_index_na_position_key(self, sort_by_key):
+        series = Series(index=[3, 2, 1, 4, 3, np.nan], dtype=object)
+        expected_series_first = Series(index=[np.nan, 1, 2, 3, 3, 4], dtype=object)
+
+        index_sorted_series = series.sort_index(na_position="first", key=sort_by_key)
+        tm.assert_series_equal(expected_series_first, index_sorted_series)
+
+        expected_series_last = Series(index=[1, 2, 3, 3, 4, np.nan], dtype=object)
+
+        index_sorted_series = series.sort_index(na_position="last", key=sort_by_key)
+        tm.assert_series_equal(expected_series_last, index_sorted_series)
+
     def test_changes_length_raises(self):
         s = Series([1, 2, 3])
         with pytest.raises(ValueError, match="change the shape"):
             s.sort_index(key=lambda x: x[:1])
+
+    def test_sort_values_key_type(self):
+        s = Series([1, 2, 3], DatetimeIndex(["2008-10-24", "2008-11-23", "2007-12-22"]))
+
+        result = s.sort_index(key=lambda x: x.month)
+        expected = s.iloc[[0, 1, 2]]
+        tm.assert_series_equal(result, expected)
+
+        result = s.sort_index(key=lambda x: x.day)
+        expected = s.iloc[[2, 1, 0]]
+        tm.assert_series_equal(result, expected)
+
+        result = s.sort_index(key=lambda x: x.year)
+        expected = s.iloc[[2, 0, 1]]
+        tm.assert_series_equal(result, expected)
+
+        result = s.sort_index(key=lambda x: x.month_name())
+        expected = s.iloc[[2, 1, 0]]
+        tm.assert_series_equal(result, expected)

pandas/tests/series/methods/test_sort_values.py

@@ -209,48 +209,3 @@ def test_sort_values_key_nan(self):
         result = series.sort_values(0, key=lambda x: -x, ascending=False)
         expected = series.iloc[[0, 4, 3, 1, 2, 5]]
         tm.assert_series_equal(result, expected)
-
-    def test_sort_index_kind_key(self, sort_by_key):
-        # GH #14444 & #13589:  Add support for sort algo choosing
-        series = Series(index=[3, 2, 1, 4, 3], dtype=object)
-        expected_series = Series(index=[1, 2, 3, 3, 4], dtype=object)
-
-        index_sorted_series = series.sort_index(kind="mergesort", key=sort_by_key)
-        tm.assert_series_equal(expected_series, index_sorted_series)
-
-        index_sorted_series = series.sort_index(kind="quicksort", key=sort_by_key)
-        tm.assert_series_equal(expected_series, index_sorted_series)
-
-        index_sorted_series = series.sort_index(kind="heapsort", key=sort_by_key)
-        tm.assert_series_equal(expected_series, index_sorted_series)
-
-    def test_sort_index_kind_neg_key(self):
-        # GH #14444 & #13589:  Add support for sort algo choosing
-        series = Series(index=[3, 2, 1, 4, 3], dtype=object)
-        expected_series = Series(index=[4, 3, 3, 2, 1], dtype=object)
-
-        index_sorted_series = series.sort_index(kind="mergesort", key=lambda x: -x)
-        tm.assert_series_equal(expected_series, index_sorted_series)
-
-        index_sorted_series = series.sort_index(kind="quicksort", key=lambda x: -x)
-        tm.assert_series_equal(expected_series, index_sorted_series)
-
-        index_sorted_series = series.sort_index(kind="heapsort", key=lambda x: -x)
-        tm.assert_series_equal(expected_series, index_sorted_series)
-
-    def test_sort_index_na_position_key(self, sort_by_key):
-        series = Series(index=[3, 2, 1, 4, 3, np.nan], dtype=object)
-        expected_series_first = Series(index=[np.nan, 1, 2, 3, 3, 4], dtype=object)
-
-        index_sorted_series = series.sort_index(na_position="first", key=sort_by_key)
-        tm.assert_series_equal(expected_series_first, index_sorted_series)
-
-        expected_series_last = Series(index=[1, 2, 3, 3, 4, np.nan], dtype=object)
-
-        index_sorted_series = series.sort_index(na_position="last", key=sort_by_key)
-        tm.assert_series_equal(expected_series_last, index_sorted_series)
-
-    def test_changes_length_raises(self):
-        s = Series([1, 2, 3])
-        with pytest.raises(ValueError, match="change the shape"):
-            s.sort_values(key=lambda x: x[:1])