DEPR: Deprecate use of strings denoting units with 'M', 'Y' or 'y' in pd.to_timedelta (36666)

doc/source/whatsnew/v1.2.0.rst

@@ -293,6 +293,7 @@ Deprecations
 - :meth:`Rolling.count` with ``min_periods=None`` will default to the size of the window in a future version (:issue:`31302`)
 - Deprecated slice-indexing on timezone-aware :class:`DatetimeIndex` with naive ``datetime`` objects, to match scalar indexing behavior (:issue:`36148`)
 - :meth:`Index.ravel` returning a ``np.ndarray`` is deprecated, in the future this will return a view on the same index (:issue:`19956`)
+- Deprecate use of strings denoting units with 'M', 'Y', 'm' or 'y' in :func:`~pandas.to_timedelta` (:issue:`36666`)
 
 .. ---------------------------------------------------------------------------
 

pandas/_libs/tslibs/timedeltas.pyx

@@ -1,4 +1,5 @@
 import collections
+import re
 
 import cython
 
@@ -1467,6 +1468,16 @@ cdef _broadcast_floordiv_td64(
         return res
 
 
+def check_unambiguous_timedelta_values(object[:] values):
+    cdef:
+        Py_ssize_t i, n = len(values)
+
+    for i in range(n):
+        if re.search(r"^\d+\s?[M|Y|m|y]$", str(values[i])):
+            return True
+    return False
+
+
 # resolution in ns
 Timedelta.min = Timedelta(np.iinfo(np.int64).min + 1)
 Timedelta.max = Timedelta(np.iinfo(np.int64).max)

pandas/core/tools/timedeltas.py

@@ -1,11 +1,17 @@
 """
 timedelta support tools
 """
+import re
+import warnings
 
 import numpy as np
 
 from pandas._libs.tslibs import NaT
-from pandas._libs.tslibs.timedeltas import Timedelta, parse_timedelta_unit
+from pandas._libs.tslibs.timedeltas import (
+    Timedelta,
+    check_unambiguous_timedelta_values,
+    parse_timedelta_unit,
+)
 
 from pandas.core.dtypes.common import is_list_like
 from pandas.core.dtypes.generic import ABCIndexClass, ABCSeries
@@ -25,10 +31,13 @@ def to_timedelta(arg, unit=None, errors="raise"):
     Parameters
     ----------
     arg : str, timedelta, list-like or Series
-        The data to be converted to timedelta.  The character M by itself,
-        e.g. '1M', is treated as minute, not month. The characters Y and y
-        are treated as the mean length of the Gregorian calendar year -
-        365.2425 days or 365 days 5 hours 49 minutes 12 seconds.
+        The data to be converted to timedelta.
+
+        .. deprecated:: 1.2
+            Strings denoting units with 'M', 'Y', 'm' or 'y' do not represent
+            unambiguous timedelta values durations and will removed in a future
+            version
+
     unit : str, optional
         Denotes the unit of the arg for numeric `arg`. Defaults to ``"ns"``.
 
@@ -101,6 +110,16 @@ def to_timedelta(arg, unit=None, errors="raise"):
             "represent unambiguous timedelta values durations."
         )
 
+    if isinstance(arg, (list, tuple, ABCSeries, ABCIndexClass, np.ndarray)):
+        arr = np.array(arg, dtype="object", ndmin=1)
+        if arr.ndim == 1 and check_unambiguous_timedelta_values(arr):
+            warnings.warn(
+                "Denoting units with 'M', 'Y', 'm' or 'y' do not represent unambiguous "
+                "timedelta values durations and will removed in a future version",
+                FutureWarning,
+                stacklevel=2,
+            )
+
     if arg is None:
         return arg
     elif isinstance(arg, ABCSeries):
@@ -118,8 +137,18 @@ def to_timedelta(arg, unit=None, errors="raise"):
             "arg must be a string, timedelta, list, tuple, 1-d array, or Series"
         )
 
-    if isinstance(arg, str) and unit is not None:
-        raise ValueError("unit must not be specified if the input is/contains a str")
+    if isinstance(arg, str):
+        if unit is not None:
+            raise ValueError(
+                "unit must not be specified if the input is/contains a str"
+            )
+        elif re.search(r"^\d+\s?[M|Y|m|y]$", arg):
+            warnings.warn(
+                "Denoting units with 'M', 'Y', 'm' or 'y' do not represent unambiguous "
+                "timedelta values durations and will removed in a future version",
+                FutureWarning,
+                stacklevel=2,
+            )
 
     # ...so it must be a scalar value. Return scalar.
     return _coerce_scalar_to_timedelta_type(arg, unit=unit, errors=errors)

pandas/tests/scalar/timedelta/test_timedelta.py

@@ -160,108 +160,119 @@ def test_nat_converters(self):
         assert result.astype("int64") == iNaT
 
     @pytest.mark.parametrize(
-        "units, np_unit",
-        [
-            (["W", "w"], "W"),
-            (["D", "d", "days", "day", "Days", "Day"], "D"),
-            (
-                ["m", "minute", "min", "minutes", "t", "Minute", "Min", "Minutes", "T"],
+        "unit, np_unit, warning",
+        [(value, "W", False) for value in ["W", "w"]]
+        + [(value, "D", False) for value in ["D", "d", "days", "day", "Days", "Day"]]
+        + [
+            (value, "m", FutureWarning if value == "m" else False)
+            for value in [
                 "m",
-            ),
-            (["s", "seconds", "sec", "second", "S", "Seconds", "Sec", "Second"], "s"),
-            (
-                [
-                    "ms",
-                    "milliseconds",
-                    "millisecond",
-                    "milli",
-                    "millis",
-                    "l",
-                    "MS",
-                    "Milliseconds",
-                    "Millisecond",
-                    "Milli",
-                    "Millis",
-                    "L",
-                ],
+                "minute",
+                "min",
+                "minutes",
+                "t",
+                "Minute",
+                "Min",
+                "Minutes",
+                "T",
+            ]
+        ]
+        + [
+            (value, "s", False)
+            for value in [
+                "s",
+                "seconds",
+                "sec",
+                "second",
+                "S",
+                "Seconds",
+                "Sec",
+                "Second",
+            ]
+        ]
+        + [
+            (value, "ms", False)
+            for value in [
                 "ms",
-            ),
-            (
-                [
-                    "us",
-                    "microseconds",
-                    "microsecond",
-                    "micro",
-                    "micros",
-                    "u",
-                    "US",
-                    "Microseconds",
-                    "Microsecond",
-                    "Micro",
-                    "Micros",
-                    "U",
-                ],
+                "milliseconds",
+                "millisecond",
+                "milli",
+                "millis",
+                "l",
+                "MS",
+                "Milliseconds",
+                "Millisecond",
+                "Milli",
+                "Millis",
+                "L",
+            ]
+        ]
+        + [
+            (value, "us", False)
+            for value in [
                 "us",
-            ),
-            (
-                [
-                    "ns",
-                    "nanoseconds",
-                    "nanosecond",
-                    "nano",
-                    "nanos",
-                    "n",
-                    "NS",
-                    "Nanoseconds",
-                    "Nanosecond",
-                    "Nano",
-                    "Nanos",
-                    "N",
-                ],
+                "microseconds",
+                "microsecond",
+                "micro",
+                "micros",
+                "u",
+                "US",
+                "Microseconds",
+                "Microsecond",
+                "Micro",
+                "Micros",
+                "U",
+            ]
+        ]
+        + [
+            (value, "ns", False)
+            for value in [
                 "ns",
-            ),
+                "nanoseconds",
+                "nanosecond",
+                "nano",
+                "nanos",
+                "n",
+                "NS",
+                "Nanoseconds",
+                "Nanosecond",
+                "Nano",
+                "Nanos",
+                "N",
+            ]
         ],
     )
     @pytest.mark.parametrize("wrapper", [np.array, list, pd.Index])
-    def test_unit_parser(self, units, np_unit, wrapper):
+    def test_unit_parser(self, unit, np_unit, wrapper, warning):
         # validate all units, GH 6855, GH 21762
-        for unit in units:
-            # array-likes
-            expected = TimedeltaIndex(
-                [np.timedelta64(i, np_unit) for i in np.arange(5).tolist()]
-            )
-            result = to_timedelta(wrapper(range(5)), unit=unit)
-            tm.assert_index_equal(result, expected)
-            result = TimedeltaIndex(wrapper(range(5)), unit=unit)
-            tm.assert_index_equal(result, expected)
-
-            if unit == "M":
-                # M is treated as minutes in string repr
-                expected = TimedeltaIndex(
-                    [np.timedelta64(i, "m") for i in np.arange(5).tolist()]
-                )
-
-            str_repr = [f"{x}{unit}" for x in np.arange(5)]
-            result = to_timedelta(wrapper(str_repr))
-            tm.assert_index_equal(result, expected)
-            result = TimedeltaIndex(wrapper(str_repr))
-            tm.assert_index_equal(result, expected)
-
-            # scalar
-            expected = Timedelta(np.timedelta64(2, np_unit).astype("timedelta64[ns]"))
-
-            result = to_timedelta(2, unit=unit)
-            assert result == expected
-            result = Timedelta(2, unit=unit)
-            assert result == expected
-
-            if unit == "M":
-                expected = Timedelta(np.timedelta64(2, "m").astype("timedelta64[ns]"))
+        # array-likes
+        expected = TimedeltaIndex(
+            [np.timedelta64(i, np_unit) for i in np.arange(5).tolist()]
+        )
+        result = to_timedelta(wrapper(range(5)), unit=unit)
+        tm.assert_index_equal(result, expected)
+        result = TimedeltaIndex(wrapper(range(5)), unit=unit)
+        tm.assert_index_equal(result, expected)
 
+        str_repr = [f"{x}{unit}" for x in np.arange(5)]
+        with tm.assert_produces_warning(warning):
+            result = to_timedelta(wrapper(str_repr))
+        tm.assert_index_equal(result, expected)
+        result = TimedeltaIndex(wrapper(str_repr))
+        tm.assert_index_equal(result, expected)
+
+        # scalar
+        expected = Timedelta(np.timedelta64(2, np_unit).astype("timedelta64[ns]"))
+        result = to_timedelta(2, unit=unit)
+        assert result == expected
+        result = Timedelta(2, unit=unit)
+        assert result == expected
+
+        with tm.assert_produces_warning(warning):
             result = to_timedelta(f"2{unit}")
-            assert result == expected
-            result = Timedelta(f"2{unit}")
-            assert result == expected
+        assert result == expected
+        result = Timedelta(f"2{unit}")
+        assert result == expected
 
     @pytest.mark.parametrize("unit", ["Y", "y", "M"])
     def test_unit_m_y_raises(self, unit):

pandas/tests/tools/test_to_timedelta.py

@@ -121,6 +121,27 @@ def test_to_timedelta_invalid(self):
             invalid_data, to_timedelta(invalid_data, errors="ignore")
         )
 
+    @pytest.mark.parametrize(
+        "val, warning",
+        [
+            ("1M", FutureWarning),
+            ("1 M", FutureWarning),
+            ("1Y", FutureWarning),
+            ("1 Y", FutureWarning),
+            ("1m", FutureWarning),
+            ("1 m", FutureWarning),
+            ("1y", FutureWarning),
+            ("1 y", FutureWarning),
+            ("1 day", None),
+            ("2day", None),
+        ],
+    )
+    def test_unambiguous_timedelta_values(self, val, warning):
+        # GH36666 Deprecate use of strings denoting units with 'M', 'Y', 'm' or 'y'
+        # in pd.to_timedelta
+        with tm.assert_produces_warning(warning):
+            to_timedelta(val)
+
     def test_to_timedelta_via_apply(self):
         # GH 5458
         expected = Series([np.timedelta64(1, "s")])