DEPR: Deprecate non-ISO date string formats in DatetimeIndex.loc

Author: raghavendranath

doc/source/whatsnew/v3.0.0.rst

@@ -739,13 +739,13 @@ Other Deprecations
 - Deprecated allowing ``fill_value`` that cannot be held in the original dtype (excepting NA values for integer and bool dtypes) in :meth:`Series.shift` and :meth:`DataFrame.shift` (:issue:`53802`)
 - Deprecated allowing strings representing full dates in :meth:`DataFrame.at_time` and :meth:`Series.at_time` (:issue:`50839`)
 - Deprecated backward-compatibility behavior for :meth:`DataFrame.select_dtypes` matching "str" dtype when ``np.object_`` is specified (:issue:`61916`)
+- Deprecated non-ISO date string formats in :meth:`DatetimeIndex.__getitem__` with string labels. Use ISO format (YYYY-MM-DD) instead. (:issue:`58302`)
 - Deprecated option "future.no_silent_downcasting", as it is no longer used. In a future version accessing this option will raise (:issue:`59502`)
 - Deprecated passing non-Index types to :meth:`Index.join`; explicitly convert to Index first (:issue:`62897`)
 - Deprecated silent casting of non-datetime 'other' to datetime in :meth:`Series.combine_first` (:issue:`62931`)
 - Deprecated slicing on a :class:`Series` or :class:`DataFrame` with a :class:`DatetimeIndex` using a ``datetime.date`` object, explicitly cast to :class:`Timestamp` instead (:issue:`35830`)
 - Deprecated support for the Dataframe Interchange Protocol (:issue:`56732`)
 - Deprecated the 'inplace' keyword from :meth:`Resampler.interpolate`, as passing ``True`` raises ``AttributeError`` (:issue:`58690`)
-
 .. ---------------------------------------------------------------------------
 .. _whatsnew_300.prior_deprecations:
 

pandas/core/indexes/datetimes.py

@@ -2,6 +2,7 @@
 
 import datetime as dt
 import operator
+import re
 from typing import (
     TYPE_CHECKING,
     Self,
@@ -110,6 +111,28 @@ def _new_DatetimeIndex(cls, d):
     return result
 
 
+def _is_iso_format_string(date_str: str) -> bool:
+    """
+    Check if a date string follows ISO8601 format.
+
+    ISO format must start with a 4-digit year (YYYY), optionally followed by
+    month and day with consistent separators.
+
+    Examples of ISO format (True):
+    - 2024-01-10
+    - 2024/01/10
+    - 2024 01 10
+    - 2024-01-10T00:00:00
+
+    Examples of non-ISO format (False):
+    - 01/10/2024 (MM/DD/YYYY)
+    - 10/01/2024 (DD/MM/YYYY)
+    - 01-10-2024 (MM-DD-YYYY)
+    """
+    # ISO format must start with 4-digit year followed by separator (-, /, ., or space)
+    return re.match(r"^\d{4}[-/. ]", date_str) is not None
+
+
 @inherit_names(
     DatetimeArray._field_ops
     + [
@@ -566,6 +589,15 @@ def _parsed_string_to_bounds(
         return start, end
 
     def _parse_with_reso(self, label: str) -> tuple[Timestamp, Resolution]:
+        # GH#58302 - Deprecate non-ISO string formats in .loc indexing
+        if isinstance(label, str) and not _is_iso_format_string(label):
+            msg = (
+                "Parsing non-ISO datetime strings in .loc is deprecated and will be "
+                "removed in a future version. Use ISO format (YYYY-MM-DD) instead. "
+                f"Got '{label}'."
+            )
+            warnings.warn(msg, Pandas4Warning, stacklevel=find_stack_level())
+
         parsed, reso = super()._parse_with_reso(label)
 
         parsed = Timestamp(parsed)
@@ -701,11 +733,29 @@ def check_str_or_none(point) -> bool:
         mask = np.array(True)
         in_index = True
         if start is not None:
+            # GH#58302 - Deprecate non-ISO string formats in .loc indexing
+            if isinstance(start, str) and not _is_iso_format_string(start):
+                msg = (
+                    "Parsing non-ISO datetime strings in .loc is deprecated "
+                    "and will be removed in a future version. Use ISO format "
+                    f"(YYYY-MM-DD) instead. Got '{start}'."
+                )
+                warnings.warn(msg, Pandas4Warning, stacklevel=find_stack_level())
+
             start_casted = self._maybe_cast_slice_bound(start, "left")
             mask = start_casted <= self
             in_index &= (start_casted == self).any()
 
         if end is not None:
+            # GH#58302 - Deprecate non-ISO string formats in .loc indexing
+            if isinstance(end, str) and not _is_iso_format_string(end):
+                msg = (
+                    "Parsing non-ISO datetime strings in .loc is deprecated "
+                    "and will be removed in a future version. Use ISO format "
+                    f"(YYYY-MM-DD) instead. Got '{end}'."
+                )
+                warnings.warn(msg, Pandas4Warning, stacklevel=find_stack_level())
+
             end_casted = self._maybe_cast_slice_bound(end, "right")
             mask = (self <= end_casted) & mask
             in_index &= (end_casted == self).any()

pandas/tests/indexes/datetimes/test_partial_slicing.py

@@ -5,6 +5,8 @@
 import numpy as np
 import pytest
 
+from pandas.errors import Pandas4Warning
+
 from pandas import (
     DataFrame,
     DatetimeIndex,
@@ -464,3 +466,96 @@ def test_slice_reduce_to_series(self):
         )
         result = df.loc["2000", "A"]
         tm.assert_series_equal(result, expected)
+
+
+class TestDatetimeIndexNonISODeprecation:
+    """Tests for deprecation of non-ISO string formats in .loc indexing. GH#58302"""
+
+    @pytest.fixture
+    def ser_daily(self):
+        """Create a Series with daily DatetimeIndex for testing."""
+        return Series(
+            range(15),
+            index=DatetimeIndex(date_range(start="2024-01-01", freq="D", periods=15)),
+        )
+
+    @pytest.mark.parametrize(
+        "date_string",
+        [
+            "1/10/2024",  # MM/DD/YYYY format
+            "01/10/2024",  # MM/DD/YYYY format with leading zero
+        ],
+    )
+    def test_loc_indexing_non_iso_single_key_deprecation(self, ser_daily, date_string):
+        # GH#58302
+        msg = "Parsing non-ISO datetime strings in .loc is deprecated"
+
+        with tm.assert_produces_warning(Pandas4Warning, match=msg):
+            result = ser_daily.loc[date_string]
+            assert result == 9
+
+    @pytest.mark.parametrize(
+        "date_string,expected",
+        [
+            ("2024-01-10", 9),  # YYYY-MM-DD (dash)
+            ("2024/01/10", 9),  # YYYY/MM/DD (slash)
+            ("2024 01 10", 9),  # YYYY MM DD (space)
+        ],
+    )
+    def test_loc_indexing_iso_format_no_warning(self, ser_daily, date_string, expected):
+        # GH#58302 - ISO formats should NOT warn
+        with tm.assert_produces_warning(None):
+            result = ser_daily.loc[date_string]
+            assert result == expected
+
+    @pytest.mark.parametrize(
+        "start_string",
+        [
+            "1/10/2024",  # MM/DD/YYYY format
+            "01/10/2024",  # MM/DD/YYYY format with leading zero
+        ],
+    )
+    def test_loc_slicing_non_iso_start_deprecation(self, ser_daily, start_string):
+        # GH#58302 - Non-ISO start in slice should warn
+        msg = "Parsing non-ISO datetime strings in .loc is deprecated"
+
+        with tm.assert_produces_warning(Pandas4Warning, match=msg):
+            result = ser_daily.loc[start_string:"2024-01-15"]
+            assert len(result) > 0
+
+    @pytest.mark.parametrize(
+        "end_string",
+        [
+            "5-01-2024",  # DD-MM-YYYY format
+            "05-01-2024",  # DD-MM-YYYY format with leading zero
+        ],
+    )
+    def test_loc_slicing_non_iso_end_deprecation(self, ser_daily, end_string):
+        # GH#58302 - Non-ISO end in slice should warn
+        msg = "Parsing non-ISO datetime strings in .loc is deprecated"
+
+        with tm.assert_produces_warning(Pandas4Warning, match=msg):
+            result = ser_daily.loc["2024-01-01":end_string]
+            assert len(result) > 0
+
+    def test_loc_slicing_both_non_iso_deprecation(self, ser_daily):
+        # GH#58302 - Both non-ISO should warn (twice)
+        msg = "Parsing non-ISO datetime strings in .loc is deprecated"
+
+        with tm.assert_produces_warning(
+            Pandas4Warning, match=msg, check_stacklevel=False
+        ):
+            result = ser_daily.loc["1/10/2024":"5-01-2024"]
+            assert len(result) > 0
+
+    def test_loc_slicing_iso_formats_no_warning(self, ser_daily):
+        # GH#58302 - ISO slice formats should NOT warn
+        with tm.assert_produces_warning(None):
+            result = ser_daily.loc["2024-01-05":"2024-01-10"]
+            assert len(result) == 6
+
+    def test_loc_non_string_keys_no_warning(self, ser_daily):
+        # GH#58302 - Non-string keys should not warn
+        with tm.assert_produces_warning(None):
+            result = ser_daily.loc[Timestamp("2024-01-10")]
+            assert result == 9