Change name

Author: TomAugspurger

pandas/core/arrays/base.py

@@ -237,16 +237,31 @@ def isna(self):
         """
         raise AbstractMethodError(self)
 
-    def _values_for_argsort(self):
+    def _simple_ndarray(self):
         # type: () -> ndarray
-        """Get the ndarray to be passed to np.argsort.
+        """Convert the array to a simple ndarray representaiton.
 
-        This is called from within 'ExtensionArray.argsort'.
+        Many methods can operate indirectly on a cheap-to-compute array that
+        is somehow representative of the extension array. For example, rather
+        than sorting an ExtensionArray directly, which might be expensive,
+        we could convert the ExtensionArray to a representative ndarray of
+        integers, sort the integers, and perform a ``take``.
+
+        The coversion between ExtensionArray and the simple ndarray should be
+        strictly monotonic https://en.wikipedia.org/wiki/Monotonic_function,
+        and as cheap to compute as possible.
 
         Returns
         -------
         values : ndarray
+
+        See Also
+        --------
+        ExtensionArray.argsort
         """
+        # Implemnetor note: This method is currently used in
+        # - ExtensionArray.argsort
+
         return np.array(self)
 
     def argsort(self, ascending=True, kind='quicksort', *args, **kwargs):
@@ -274,11 +289,11 @@ def argsort(self, ascending=True, kind='quicksort', *args, **kwargs):
         """
         # Implementor note: You have two places to override the behavior of
         # argsort.
-        # 1. _values_for_argsort : construct the values passed to np.argsort
+        # 1. _simple_ndarray : construct the values passed to np.argsort
         # 2. argsort : total control over sorting.
 
         ascending = nv.validate_argsort_with_ascending(ascending, args, kwargs)
-        values = self._values_for_argsort()
+        values = self._simple_ndarray()
         result = np.argsort(values, kind=kind, **kwargs)
         if not ascending:
             result = result[::-1]

pandas/core/arrays/categorical.py

@@ -1390,7 +1390,7 @@ def check_for_ordered(self, op):
                             "you can use .as_ordered() to change the "
                             "Categorical to an ordered one\n".format(op=op))
 
-    def _values_for_argsort(self):
+    def _simple_ndarray(self):
         return self._codes.copy()
 
     def argsort(self, *args, **kwargs):