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/core/tools/timedeltas.py

@@ -1,6 +1,8 @@
 """
 timedelta support tools
 """
+import re
+import warnings
 
 import numpy as np
 
@@ -25,10 +27,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"``.
 
@@ -118,8 +123,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

@@ -258,7 +258,9 @@ def test_unit_parser(self, units, np_unit, wrapper):
             if unit == "M":
                 expected = Timedelta(np.timedelta64(2, "m").astype("timedelta64[ns]"))
 
-            result = to_timedelta(f"2{unit}")
+            warning = None if unit != "m" else FutureWarning
+            with tm.assert_produces_warning(warning):
+                result = to_timedelta(f"2{unit}")
             assert result == expected
             result = Timedelta(f"2{unit}")
             assert result == expected

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")])