Change True to None; disallow True

Author: jorisvandenbossche

doc/source/whatsnew/v0.24.1.rst

@@ -20,74 +20,24 @@ including other versions of pandas.
 API Changes
 ~~~~~~~~~~~
 
-Changing the ``sort`` parameter for :meth:`Index.union`
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Changing the ``sort`` parameter for :class:`Index` set operations
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 The default ``sort`` value for :meth:`Index.union` has changed from ``True`` to ``None`` (:issue:`24959`).
-The default *behavior* remains the same: The result is sorted, unless
+The default *behavior*, however, remains the same: the result is sorted, unless
 
 1. ``self`` and ``other`` are identical
 2. ``self`` or ``other`` is empty
 3. ``self`` or ``other`` contain values that can not be compared (a ``RuntimeWarning`` is raised).
 
-This allows ``sort=True`` to now mean "always sort". A ``TypeError`` is raised if the values cannot be compared.
-
-**Behavior in 0.24.0**
-
-.. ipython:: python
-
-   In [1]: idx = pd.Index(['b', 'a'])
-
-   In [2]: idx.union(idx)  # sort=True was the default.
-   Out[2]: Index(['b', 'a'], dtype='object')
-
-   In [3]: idx.union(idx, sort=True)  # result is still not sorted.
-   Out[32]: Index(['b', 'a'], dtype='object')
-
-**New Behavior**
-
-.. ipython:: python
-
-   idx = pd.Index(['b', 'a'])
-   idx.union(idx)  # sort=None is the default. Don't sort identical operands.
-
-   idx.union(idx, sort=True)
+This change will allow to preserve ``sort=True`` to mean "always sort" in a future release.
 
 The same change applies to :meth:`Index.difference` and :meth:`Index.symmetric_difference`, which
-would previously not sort the result when ``sort=True`` but the values could not be compared.
-
-Changed the behavior of :meth:`Index.intersection` with ``sort=True``
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-When ``sort=True`` is provided to :meth:`Index.intersection`, the values are always sorted. In 0.24.0,
-the values would not be sorted when ``self`` and ``other`` were identical. Pass ``sort=False`` to not
-sort the values. This matches the behavior of pandas 0.23.4 and earlier.
-
-**Behavior in 0.23.4**
-
-.. ipython:: python
-
-   In [2]: idx = pd.Index(['b', 'a'])
-
-   In [3]: idx.intersection(idx)  # sort was not a keyword.
-   Out[3]: Index(['b', 'a'], dtype='object')
-
-**Behavior in 0.24.0**
-
-.. ipython:: python
-
-   In [5]: idx.intersection(idx)  # sort=True by default. Don't sort identical.
-   Out[5]: Index(['b', 'a'], dtype='object')
-
-   In [6]: idx.intersection(idx, sort=True)
-   Out[6]: Index(['b', 'a'], dtype='object')
-
-**New Behavior**
-
-.. ipython:: python
+would do not sort the result when the values could not be compared.
 
-   idx.intersection(idx)  # sort=False by default
-   idx.intersection(idx, sort=True)
+For :meth:`Index.intersection` the option of ``sort=True`` is also renamed
+to ``sort=None`` (but for :meth:`Index.intersection` it is not the default), as
+the result is not sorted when ``self`` and ``other`` were identical.
 
 .. _whatsnew_0241.regressions:
 

pandas/_libs/lib.pyx

@@ -239,8 +239,6 @@ def fast_unique_multiple(list arrays, sort: bool=True):
         except Exception:
             # TODO: RuntimeWarning?
             pass
-    elif sort:
-        uniques.sort()
 
     return uniques
 

pandas/core/indexes/base.py

@@ -2245,6 +2245,11 @@ def _get_reconciled_name_object(self, other):
             return self._shallow_copy(name=name)
         return self
 
+    def _validate_sort_keyword(self, sort):
+        if sort not in [None, False]:
+            raise ValueError("The 'sort' keyword only takes the values of "
+                             "None or False; {0} was passed.".format(sort))
+
     def union(self, other, sort=None):
         """
         Form the union of two Index objects.
@@ -2262,16 +2267,14 @@ def union(self, other, sort=None):
               3. Some values in `self` or `other` cannot be compared.
                  A RuntimeWarning is issued in this case.
 
-            * True : sort the result. A TypeError is raised when the
-              values cannot be compared.
             * False : do not sort the result.
 
             .. versionadded:: 0.24.0
 
             .. versionchanged:: 0.24.1
 
-               Changed the default `sort` to None, matching the
-               behavior of pandas 0.23.4 and earlier.
+               Changed the default `sort` from True to None (without
+               change in behaviour).
 
         Returns
         -------
@@ -2285,20 +2288,15 @@ def union(self, other, sort=None):
         >>> idx1.union(idx2)
         Int64Index([1, 2, 3, 4, 5, 6], dtype='int64')
         """
+        self._validate_sort_keyword(sort)
         self._assert_can_do_setop(other)
         other = ensure_index(other)
 
         if len(other) == 0 or self.equals(other):
-            result = self._get_reconciled_name_object(other)
-            if sort:
-                result = result.sort_values()
-            return result
+            return self._get_reconciled_name_object(other)
 
         if len(self) == 0:
-            result = other._get_reconciled_name_object(self)
-            if sort:
-                result = result.sort_values()
-            return result
+            return other._get_reconciled_name_object(self)
 
         # TODO: is_dtype_union_equal is a hack around
         # 1. buggy set ops with duplicates (GH #13432)
@@ -2348,9 +2346,6 @@ def union(self, other, sort=None):
                     warnings.warn("{}, sort order is undefined for "
                                   "incomparable objects".format(e),
                                   RuntimeWarning, stacklevel=3)
-            elif sort:
-                # raise if not sortable.
-                result = sorting.safe_sort(result)
 
         # for subclasses
         return self._wrap_setop_result(other, result)
@@ -2367,12 +2362,12 @@ def intersection(self, other, sort=False):
         Parameters
         ----------
         other : Index or array-like
-        sort : bool or None, default False
+        sort : False or None, default False
             Whether to sort the resulting index.
 
             * False : do not sort the result.
-            * True : sort the result. A TypeError is raised when the
-              values cannot be compared.
+            * None : sort the result, except when `self` and `other` are equal
+              or when the values cannot be compared. 
 
             .. versionadded:: 0.24.0
 
@@ -2392,14 +2387,12 @@ def intersection(self, other, sort=False):
         >>> idx1.intersection(idx2)
         Int64Index([3, 4], dtype='int64')
         """
+        self._validate_sort_keyword(sort)
         self._assert_can_do_setop(other)
         other = ensure_index(other)
 
         if self.equals(other):
-            result = self._get_reconciled_name_object(other)
-            if sort:
-                result = result.sort_values()
-            return result
+            return self._get_reconciled_name_object(other)
 
         if not is_dtype_equal(self.dtype, other.dtype):
             this = self.astype('O')
@@ -2434,7 +2427,7 @@ def intersection(self, other, sort=False):
 
         taken = other.take(indexer)
 
-        if sort:
+        if sort is None:
             taken = sorting.safe_sort(taken.values)
             if self.name != other.name:
                 name = None
@@ -2457,22 +2450,20 @@ def difference(self, other, sort=None):
         Parameters
         ----------
         other : Index or array-like
-        sort : bool or None, default None
+        sort : False or None, default None
             Whether to sort the resulting index. By default, the
             values are attempted to be sorted, but any TypeError from
             incomparable elements is caught by pandas.
 
             * None : Attempt to sort the result, but catch any TypeErrors
               from comparing incomparable elements.
             * False : Do not sort the result.
-            * True : Sort the result, raising a TypeError if any elements
-              cannot be compared.
 
             .. versionadded:: 0.24.0
 
             .. versionchanged:: 0.24.1
 
-               Added the `None` option, which matches the behavior of
+               Changed `True` to `None`, which matches the behavior of
                pandas 0.23.4 and earlier.
 
         Returns
@@ -2489,6 +2480,7 @@ def difference(self, other, sort=None):
         >>> idx1.difference(idx2, sort=False)
         Int64Index([2, 1], dtype='int64')
         """
+        self._validate_sort_keyword(sort)
         self._assert_can_do_setop(other)
 
         if self.equals(other):
@@ -2510,8 +2502,6 @@ def difference(self, other, sort=None):
                 the_diff = sorting.safe_sort(the_diff)
             except TypeError:
                 pass
-        elif sort:
-            the_diff = sorting.safe_sort(the_diff)
 
         return this._shallow_copy(the_diff, name=result_name, freq=None)
 
@@ -2523,22 +2513,20 @@ def symmetric_difference(self, other, result_name=None, sort=None):
         ----------
         other : Index or array-like
         result_name : str
-        sort : bool or None, default None
+        sort : False or None, default None
             Whether to sort the resulting index. By default, the
             values are attempted to be sorted, but any TypeError from
             incomparable elements is caught by pandas.
 
             * None : Attempt to sort the result, but catch any TypeErrors
               from comparing incomparable elements.
             * False : Do not sort the result.
-            * True : Sort the result, raising a TypeError if any elements
-              cannot be compared.
 
             .. versionadded:: 0.24.0
 
             .. versionchanged:: 0.24.1
 
-               Added the `None` option, which matches the behavior of
+               Changed `True` to `None`, which matches the behavior of
                pandas 0.23.4 and earlier.
 
         Returns
@@ -2564,6 +2552,7 @@ def symmetric_difference(self, other, result_name=None, sort=None):
         >>> idx1 ^ idx2
         Int64Index([1, 5], dtype='int64')
         """
+        self._validate_sort_keyword(sort)
         self._assert_can_do_setop(other)
         other, result_name_update = self._convert_can_do_setop(other)
         if result_name is None:
@@ -2589,8 +2578,6 @@ def symmetric_difference(self, other, result_name=None, sort=None):
                 the_diff = sorting.safe_sort(the_diff)
             except TypeError:
                 pass
-        elif sort:
-            the_diff = sorting.safe_sort(the_diff)
 
         attribs = self._get_attributes_dict()
         attribs['name'] = result_name

pandas/core/indexes/datetimes.py

@@ -602,19 +602,21 @@ def intersection(self, other, sort=False):
         Parameters
         ----------
         other : DatetimeIndex or array-like
-        sort : bool, default True
+        sort : False or None, default False
             Sort the resulting index if possible.
 
             .. versionadded:: 0.24.0
 
             .. versionchanged:: 0.24.1
 
-               Changed the default from ``True`` to ``False``.
+               Changed the default to ``False`` to match the behaviour
+               from before 0.24.0.
 
         Returns
         -------
         y : Index or DatetimeIndex
         """
+        self._validate_sort_keyword(sort)
         self._assert_can_do_setop(other)
 
         if self.equals(other):

pandas/core/indexes/interval.py

@@ -1093,7 +1093,7 @@ def equals(self, other):
     def overlaps(self, other):
         return self._data.overlaps(other)
 
-    def _setop(op_name, sort=True):
+    def _setop(op_name, sort=None):
         def func(self, other, sort=sort):
             other = self._as_like_interval_index(other)