DEPR: deprecate dates-with-datetime64 in _maybe_downcast_for_indexing

Deprecate the special case in Index._maybe_downcast_for_indexing that
implicitly converts sequences of datetime.date objects to DatetimeIndex
when joining or indexing. This affects join, alignment, and get_indexer
fallback paths where _maybe_cast_listlike_indexer does not handle the
conversion.

closes #62158

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: jbrockmendel

doc/source/whatsnew/v3.1.0.rst

@@ -99,6 +99,7 @@ Deprecations
 - Deprecated :meth:`ExcelFile.parse`, use :func:`read_excel` instead (:issue:`58247`)
 - Deprecated arithmetic operations between pandas objects (:class:`DataFrame`, :class:`Series`, :class:`Index`, and pandas-implemented :class:`ExtensionArray` subclasses) and list-likes other than ``list``, ``np.ndarray``, :class:`ExtensionArray`, :class:`Index`, :class:`Series`, :class:`DataFrame`. For e.g. ``tuple`` or ``range``, explicitly cast these to a supported object instead. In a future version, these will be treated as scalar-like for pointwise operation (:issue:`62423`)
 - Deprecated automatic dtype promotion when reindexing with a ``fill_value`` that cannot be held by the original dtype. Explicitly cast to a common dtype instead (:issue:`53910`)
+- Deprecated implicit conversion of ``datetime.date`` objects to :class:`Timestamp` when indexing or joining a :class:`DatetimeIndex`. Use :func:`to_datetime` to explicitly convert to :class:`DatetimeIndex` instead (:issue:`62158`)
 - Deprecated passing unnecessary ``*args`` and ``**kwargs`` to :meth:`.GroupBy.cumsum`, :meth:`.GroupBy.cumprod`, :meth:`.GroupBy.cummin`, :meth:`.GroupBy.cummax`, :meth:`.SeriesGroupBy.skew`, :meth:`.DataFrameGroupBy.skew`, :meth:`.SeriesGroupBy.take`, and :meth:`.DataFrameGroupBy.take`. The ``skipna`` parameter for the cum* methods is now an explicit keyword argument (:issue:`50407`)
 - Deprecated the ``.name`` property of offset objects (e.g., :class:`~pandas.tseries.offsets.Day`, :class:`~pandas.tseries.offsets.Hour`). Use ``.rule_code`` instead (:issue:`64207`)
 - Deprecated the ``xlrd`` and ``pyxlsb`` engines in :func:`read_excel`. Use ``engine="calamine"`` instead (:issue:`56542`)

pandas/core/indexes/base.py

@@ -6534,9 +6534,18 @@ def _maybe_downcast_for_indexing(self, other: Index) -> tuple[Index, Index]:
 
         elif self.inferred_type == "date" and isinstance(other, ABCDatetimeIndex):
             try:
-                return type(other)(self), other
+                result = type(other)(self), other
             except OutOfBoundsDatetime:
                 return self, other
+            else:
+                warnings.warn(
+                    # GH#62158 deprecate special-case treatment of date objects
+                    "Indexing a DatetimeIndex with a sequence of datetime.date "
+                    "objects is deprecated. Use Timestamp objects instead.",
+                    Pandas4Warning,
+                    stacklevel=find_stack_level(),
+                )
+                return result
         elif self.inferred_type == "timedelta" and isinstance(other, ABCTimedeltaIndex):
             # TODO: we dont have tests that get here
             return type(other)(self), other

pandas/tests/frame/methods/test_asfreq.py

@@ -4,6 +4,7 @@
 import pytest
 
 from pandas._libs.tslibs.offsets import MonthEnd
+from pandas.errors import Pandas4Warning
 
 from pandas import (
     DataFrame,
@@ -192,7 +193,10 @@ def test_asfreq_with_date_object_index(self, frame_or_series):
         ts2 = ts.copy()
         ts2.index = [x.date() for x in ts2.index]
 
-        result = ts2.asfreq("4h", method="ffill")
+        # GH#62158 date-object Index reindexed against DatetimeIndex
+        msg = "Indexing a DatetimeIndex with a sequence of datetime.date"
+        with tm.assert_produces_warning(Pandas4Warning, match=msg):
+            result = ts2.asfreq("4h", method="ffill")
         expected = ts.asfreq("4h", method="ffill")
         tm.assert_equal(result, expected)
 

pandas/tests/indexes/datetimes/test_indexing.py

@@ -604,7 +604,11 @@ def test_get_indexer(self):
     def test_get_indexer_mixed_dtypes(self, target):
         # https://github.com/pandas-dev/pandas/issues/33741
         values = DatetimeIndex([Timestamp("2020-01-01"), Timestamp("2020-01-02")])
-        result = values.get_indexer(target)
+        # GH#62158 mixed date/Timestamp list infers as "date", triggering
+        # the _maybe_downcast_for_indexing fallback
+        msg = "Indexing a DatetimeIndex with a sequence of datetime.date"
+        with tm.assert_produces_warning(Pandas4Warning, match=msg):
+            result = values.get_indexer(target)
         expected = np.array([0, 1], dtype=np.intp)
         tm.assert_numpy_array_equal(result, expected)
 
@@ -617,9 +621,12 @@ def test_get_indexer_mixed_dtypes(self, target):
         ],
     )
     def test_get_indexer_out_of_bounds_date(self, target, positions):
+        # GH#62158
         values = DatetimeIndex([Timestamp("2020-01-01"), Timestamp("2020-01-02")])
 
-        result = values.get_indexer(target)
+        msg = "Indexing a DatetimeIndex with a sequence of datetime.date"
+        with tm.assert_produces_warning(Pandas4Warning, match=msg):
+            result = values.get_indexer(target)
         expected = np.array(positions, dtype=np.intp)
         tm.assert_numpy_array_equal(result, expected)
 

pandas/tests/indexes/datetimes/test_join.py

@@ -1,11 +1,14 @@
 from datetime import (
+    date,
     datetime,
     timezone,
 )
 
 import numpy as np
 import pytest
 
+from pandas.errors import Pandas4Warning
+
 from pandas import (
     DataFrame,
     DatetimeIndex,
@@ -151,3 +154,14 @@ def test_join_preserves_freq(self, tz):
         assert result.freq is None
         expected = dti.delete(5)
         tm.assert_index_equal(result, expected)
+
+
+def test_join_date_objects_with_datetimeindex():
+    # GH#62158
+    dti = date_range("2016-01-01", periods=3)
+    date_idx = Index([date(2016, 1, 1), date(2016, 1, 2), date(2016, 1, 3)])
+
+    msg = "Indexing a DatetimeIndex with a sequence of datetime.date"
+    with tm.assert_produces_warning(Pandas4Warning, match=msg):
+        result = dti.join(date_idx, how="inner")
+    tm.assert_index_equal(result, dti)

pandas/tests/series/test_arithmetic.py

@@ -895,8 +895,11 @@ def test_align_date_objects_with_datetimeindex(self):
         ts2 = ts_slice.copy()
         ts2.index = [x.date() for x in ts2.index]
 
-        result = ts + ts2
-        result2 = ts2 + ts
+        # GH#62158 alignment joins date-object Index with DatetimeIndex
+        msg = "Indexing a DatetimeIndex with a sequence of datetime.date"
+        with tm.assert_produces_warning(Pandas4Warning, match=msg):
+            result = ts + ts2
+            result2 = ts2 + ts
         expected = ts + ts[5:]
         expected.index = expected.index._with_freq(None)
         tm.assert_series_equal(result, expected)