fixed small bug with datetimelike, updated docs

Author: jacobaustin123

doc/source/user_guide/basics.rst

@@ -1786,7 +1786,7 @@ used to sort a pandas object by its index levels.
 .. versionadded:: 1.1.0
 
 Sorting by index also supports a ``key`` parameter that takes a callable
-function to apply to the index being sorted. for `MultiIndex` objects,
+function to apply to the index being sorted. For `MultiIndex` objects,
 the key is applied per-level to the levels specified by `level`.
 
 .. ipython:: python

doc/source/whatsnew/v1.1.0.rst

@@ -44,8 +44,8 @@ Sorting with keys
 We've added a ``key`` argument to the DataFrame and Series sorting methods, including
 :meth:`DataFrame.sort_values`, :meth:`DataFrame.sort_index`, :meth:`Series.sort_values`,
 and :meth:`Series.sort_index`. The ``key`` can be any callable function which is applied
-to the each column of a DataFrame before sorting is performed (:issue:`27237`). See
-:ref:`sort_values with keys <basics.sort_value_key>` and :ref:`sort_index with keys
+column-by-column to each column used for sorting, before sorting is performed (:issue:`27237`). 
+See :ref:`sort_values with keys <basics.sort_value_key>` and :ref:`sort_index with keys
 <basics.sort_index_key>` for more information.
 
 .. ipython:: python
@@ -54,11 +54,12 @@ to the each column of a DataFrame before sorting is performed (:issue:`27237`).
    s.sort_values()
 
 
-Note how this is sorted with capital letters first. If we apply the `ser.str.lower()` method, we get
+Note how this is sorted with capital letters first. If we apply the :meth:`Series.str.lower` 
+method, we get
 
 .. ipython:: python
 
-   s.sort_values(key=lambda x: x.str.lower)
+   s.sort_values(key=lambda x: x.str.lower())
 
 
 When applied to a `DataFrame`, they key is applied per-column to all columns or a subset if

pandas/core/generic.py

@@ -4217,7 +4217,7 @@ def sort_values(
 
         Sorting with a key function
 
-        >>> df.sort_values(by='col4', key=lambda col : col.str.lower())
+        >>> df.sort_values(by='col4', key=lambda col: col.str.lower())
            col1  col2  col3 col4
         0    A     2     0    a
         1    A     1     1    B

pandas/core/indexes/datetimelike.py

@@ -185,9 +185,10 @@ def sort_values(self, return_indexer=False, ascending=True, key=None):
             # 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.
-            sorted_values = np.sort(idx.asi8)
+            _as = np.argsort(idx.asi8)
+            sorted_values = self.asi8[_as]
 
-            freq = idx.freq
+            freq = self.freq
             if freq is not None and not is_period_dtype(self):
                 if freq.n > 0 and not ascending:
                     freq = freq * -1
@@ -197,7 +198,7 @@ def sort_values(self, return_indexer=False, ascending=True, key=None):
             if not ascending:
                 sorted_values = sorted_values[::-1]
 
-            arr = type(idx._data)._simple_new(
+            arr = type(self._data)._simple_new(
                 sorted_values, dtype=self.dtype, freq=freq
             )
             return type(self)._simple_new(arr, name=self.name)

pandas/core/sorting.py

@@ -319,32 +319,32 @@ def nargsort(
     return indexer
 
 
-def ensure_key_mapped_multiindex(index, key, level=None):
+def ensure_key_mapped_multiindex(index, key: Callable, level=None):
+    """
+    Returns a new MultiIndex in which key has been applied
+    to all levels specified in level (or all levels if level
+    is None). Used for key sorting for MultiIndex.
+
+    Parameters
+    ----------
+    index : MultiIndex
+        Index to which to apply the key function on the
+        specified levels.
+    key : Callable
+        Function that takes an Index and returns an Index of
+        the same shape. This key is applied to each level
+        separately. The name of the level can be used to
+        distinguish different levels for application.
+    level : list-like, int or str, default None
+        Level or list of levels to apply the key function to.
+        If None, key function is applied to all levels. Other
+        levels are left unchanged.
+
+    Returns
+    -------
+    labels : MultiIndex
+        Resulting MultiIndex with modified levels.
     """
-        Returns a new MultiIndex in which key has been applied
-        to all levels specified in level (or all levels if level
-        is None). Used for key sorting for MultiIndex.
-
-        Parameters
-        ----------
-        index : MultiIndex
-            Index to which to apply the key function on the
-            specified levels.
-        key : Callable
-            Function that takes an Index and returns an Index of
-            the same shape. This key is applied to each level
-            separately. The name of the level can be used to
-            distinguish different levels for application.
-        level : list-like, int or str, default None
-            Level or list of levels to apply the key function to.
-            If None, key function is applied to all levels. Other
-            levels are left unchanged.
-
-        Returns
-        -------
-        labels : MultiIndex
-            Resulting MultiIndex with modified levels.
-        """
     from pandas.core.indexes.api import MultiIndex
 
     if level is not None: