Deprecate with union_indexes

Author: rhshadrach

pandas/core/apply.py

@@ -637,6 +637,7 @@ def wrap_results_dict_like(
                 results,
                 axis=axis,
                 keys=keys_to_use,
+                sort=False,
             )
         elif any(is_ndframe):
             # There is a mix of NDFrames and scalars

pandas/core/indexes/api.py

@@ -227,6 +227,7 @@ def union_indexes(indexes, sort: bool | None = True) -> Index:
             raise TypeError("Cannot join tz-naive with tz-aware DatetimeIndex")
 
         if num_dtis == len(indexes):
+            # sort = True
             result = indexes[0]
 
         elif num_dtis > 1:

pandas/core/reshape/concat.py

@@ -46,6 +46,7 @@
     get_objs_combined_axis,
     get_unanimous_names,
 )
+from pandas.core.indexes.datetimes import DatetimeIndex
 from pandas.core.internals import concatenate_managers
 
 if TYPE_CHECKING:
@@ -162,7 +163,7 @@ def concat(
     levels=None,
     names: list[HashableT] | None = None,
     verify_integrity: bool = False,
-    sort: bool = False,
+    sort: bool | lib.NoDefault = lib.no_default,
     copy: bool | lib.NoDefault = lib.no_default,
 ) -> DataFrame | Series:
     """
@@ -405,14 +406,39 @@ def concat(
             "Only can inner (intersect) or outer (union) join the other axis"
         )
 
-    if not is_bool(sort):
-        raise ValueError(
-            f"The 'sort' keyword only accepts boolean values; {sort} was passed."
-        )
-    sort = bool(sort)
-
     objs, keys, ndims = _clean_keys_and_objs(objs, keys)
 
+    if sort is lib.no_default:
+        if axis == 0:
+            non_concat_axis = [
+                obj.columns if isinstance(obj, ABCDataFrame) else Index([obj.name])
+                for obj in objs
+            ]
+        else:
+            non_concat_axis = [obj.index for obj in objs]
+
+        if all(isinstance(index, DatetimeIndex) for index in non_concat_axis):
+            from pandas.core.indexes.api import union_indexes
+
+            no_sort_result_index = union_indexes(non_concat_axis, sort=False)
+            if not no_sort_result_index.is_monotonic_increasing:
+                msg = (
+                    "Sorting by default when concatenating all DatetimeIndex is "
+                    "deprecated.  In the future, pandas will respect the default "
+                    "of `sort=False`. Specify `sort=True` or `sort=False` to "
+                    "silence this message."
+                )
+                warnings.warn(msg, Pandas4Warning, stacklevel=find_stack_level())
+            sort = True
+        else:
+            sort = False
+    else:
+        if not is_bool(sort):
+            raise ValueError(
+                f"The 'sort' keyword only accepts boolean values; {sort} was passed."
+            )
+        sort = bool(sort)
+
     # select an object to be our result reference
     sample, objs = _get_sample_object(objs, ndims, keys, names, levels, intersect)
 

pandas/core/reshape/merge.py

@@ -1125,7 +1125,7 @@ def _reindex_and_concat(
 
         left.columns = llabels
         right.columns = rlabels
-        result = concat([left, right], axis=1)
+        result = concat([left, right], axis=1, sort=False)
         return result
 
     def get_result(self) -> DataFrame:

pandas/tests/reshape/concat/test_concat.py

@@ -10,7 +10,10 @@
 import numpy as np
 import pytest
 
-from pandas.errors import InvalidIndexError
+from pandas.errors import (
+    InvalidIndexError,
+    Pandas4Warning,
+)
 
 import pandas as pd
 from pandas import (
@@ -434,7 +437,9 @@ def test_concat_bug_1719(self):
         # to join with union
         # these two are of different length!
         left = concat([ts1, ts2], join="outer", axis=1)
-        right = concat([ts2, ts1], join="outer", axis=1)
+        msg = "Sorting by default when concatenating all DatetimeIndex"
+        with tm.assert_produces_warning(Pandas4Warning, match=msg):
+            right = concat([ts2, ts1], join="outer", axis=1)
 
         assert len(left) == len(right)
 

pandas/tests/reshape/concat/test_datetimes.py

@@ -5,6 +5,8 @@
 import numpy as np
 import pytest
 
+from pandas.errors import Pandas4Warning
+
 import pandas as pd
 from pandas import (
     DataFrame,
@@ -69,27 +71,29 @@ def test_concat_datetime_timezone(self):
 
         idx3 = date_range("2011-01-01", periods=3, freq="h", tz="Asia/Tokyo")
         df3 = DataFrame({"b": [1, 2, 3]}, index=idx3)
-        result = concat([df1, df3], axis=1)
+        msg = "Sorting by default when concatenating all DatetimeIndex"
+        with tm.assert_produces_warning(Pandas4Warning, match=msg):
+            result = concat([df1, df3], axis=1)
 
         exp_idx = DatetimeIndex(
             [
-                "2010-12-31 23:00:00+00:00",
-                "2011-01-01 00:00:00+00:00",
-                "2011-01-01 01:00:00+00:00",
                 "2010-12-31 15:00:00+00:00",
                 "2010-12-31 16:00:00+00:00",
                 "2010-12-31 17:00:00+00:00",
+                "2010-12-31 23:00:00+00:00",
+                "2011-01-01 00:00:00+00:00",
+                "2011-01-01 01:00:00+00:00",
             ]
         ).as_unit("ns")
 
         expected = DataFrame(
             [
-                [1, np.nan],
-                [2, np.nan],
-                [3, np.nan],
                 [np.nan, 1],
                 [np.nan, 2],
                 [np.nan, 3],
+                [1, np.nan],
+                [2, np.nan],
+                [3, np.nan],
             ],
             index=exp_idx,
             columns=["a", "b"],