DEPR: deprecate dates-with-datetime64 in _maybe_downcast_for_indexing (#64871)

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

Author: jbrockmendel

doc/source/whatsnew/v3.1.0.rst

@@ -103,6 +103,7 @@ Deprecations
 - 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 grouping by an index level name when the name matches multiple levels of a :class:`MultiIndex`. Use the level number instead (:issue:`49434`)
+- 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 a ``dict`` to :meth:`DataFrame.from_records`, use the :class:`DataFrame` constructor or :meth:`DataFrame.from_dict` instead (:issue:`22025`)
 - Deprecated passing a non-dict (e.g. a list of dicts) to :meth:`DataFrame.from_dict`. Use the :class:`DataFrame` constructor instead (:issue:`58862`)
 - 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`)

pandas/core/indexes/base.py

@@ -6603,9 +6603,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

@@ -606,7 +606,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)
 
@@ -619,9 +623,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,7 +895,8 @@ def test_align_date_objects_with_datetimeindex(self):
         ts2 = ts_slice.copy()
         ts2.index = [x.date() for x in ts2.index]
 
-        msg = "object-dtype Index of datetime.date objects is deprecated"
+        # GH#62158 alignment joins date-object Index with DatetimeIndex
+        msg = "Alignment of a DataFrame/Series with a DatetimeIndex"
         with tm.assert_produces_warning(Pandas4Warning, match=msg):
             result = ts + ts2
             result2 = ts2 + ts