DEPR: Add Deprecated warning for timedelta with passed units M and Y

doc/source/whatsnew/v0.24.0.rst

@@ -1315,6 +1315,7 @@ Deprecations
 - The ``keep_tz=False`` option (the default) of the ``keep_tz`` keyword of
   :meth:`DatetimeIndex.to_series` is deprecated (:issue:`17832`).
 - Timezone converting a tz-aware ``datetime.datetime`` or :class:`Timestamp` with :class:`Timestamp` and the ``tz`` argument is now deprecated. Instead, use :meth:`Timestamp.tz_convert` (:issue:`23579`)
+<<<<<<< HEAD
 - :func:`pandas.api.types.is_period` is deprecated in favor of ``pandas.api.types.is_period_dtype`` (:issue:`23917`)
 - :func:`pandas.api.types.is_datetimetz` is deprecated in favor of ``pandas.api.types.is_datetime64tz`` (:issue:`23917`)
 - Creating a :class:`TimedeltaIndex`, :class:`DatetimeIndex`, or :class:`PeriodIndex` by passing range arguments `start`, `end`, and `periods` is deprecated in favor of :func:`timedelta_range`, :func:`date_range`, or :func:`period_range` (:issue:`23919`)
@@ -1327,6 +1328,7 @@ Deprecations
 - ``Series.cat.categorical``, ``Series.cat.name`` and ``Sersies.cat.index`` have been deprecated. Use the attributes on ``Series.cat`` or ``Series`` directly. (:issue:`24751`).
 - Passing a dtype without a precision like ``np.dtype('datetime64')`` or ``timedelta64`` to :class:`Index`, :class:`DatetimeIndex` and :class:`TimedeltaIndex` is now deprecated. Use the nanosecond-precision dtype instead (:issue:`24753`).
 
+
 .. _whatsnew_0240.deprecations.datetimelike_int_ops:
 
 Integer Addition/Subtraction with Datetimes and Timedeltas is Deprecated

doc/source/whatsnew/v0.25.0.rst

@@ -42,10 +42,7 @@ Other API Changes
 Deprecations
 ~~~~~~~~~~~~
 
--
--
--
-
+- Deprecated the `M (months)` and `Y (year)` `units` parameter of :func: `pandas.to_timedelta`, :func: `pandas.Timedelta` and :func: `pandas.TimedeltaIndex` (:issue:`16344`)
 
 .. _whatsnew_0250.prior_deprecations:
 

pandas/_libs/tslibs/timedeltas.pyx

@@ -1185,6 +1185,11 @@ class Timedelta(_Timedelta):
                 "Value must be Timedelta, string, integer, "
                 "float, timedelta or convertible")
 
+        if unit in {'Y', 'y', 'M'}:
+            warnings.warn("M and Y units are deprecated and "
+                          "will be removed in a future version.",
+                          FutureWarning, stacklevel=3)
+
         if is_timedelta64_object(value):
             value = value.view('i8')
 

pandas/core/indexes/timedeltas.py

@@ -207,6 +207,11 @@ def __new__(cls, data=None, unit=None, freq=None, start=None, end=None,
                             'collection of some kind, {data} was passed'
                             .format(cls=cls.__name__, data=repr(data)))
 
+        if unit in {'Y', 'y', 'M'}:
+            warnings.warn("M and Y units are deprecated and "
+                          "will be removed in a future version.",
+                          FutureWarning, stacklevel=2)
+
         if isinstance(data, TimedeltaArray):
             if copy:
                 data = data.copy()

pandas/core/tools/timedeltas.py

@@ -2,6 +2,8 @@
 timedelta support tools
 """
 
+import warnings
+
 import numpy as np
 
 from pandas._libs.tslibs.timedeltas import Timedelta, parse_timedelta_unit
@@ -90,6 +92,11 @@ def to_timedelta(arg, unit='ns', box=True, errors='raise'):
         raise ValueError("errors must be one of 'ignore', "
                          "'raise', or 'coerce'}")
 
+    if unit in {'Y', 'y', 'M'}:
+        warnings.warn("M and Y units are deprecated and "
+                      "will be removed in a future version.",
+                      FutureWarning, stacklevel=2)
+
     if arg is None:
         return arg
     elif isinstance(arg, ABCSeries):

pandas/tests/indexes/timedeltas/test_timedelta.py

@@ -1,4 +1,5 @@
 from datetime import timedelta
+import re
 
 import numpy as np
 import pytest
@@ -325,6 +326,14 @@ def test_freq_conversion(self):
         result = td.astype('timedelta64[s]')
         assert_index_equal(result, expected)
 
+    @pytest.mark.parametrize('unit', ['Y', 'y', 'M'])
+    def test_unit_m_y_deprecated(self, unit):
+        with tm.assert_produces_warning(FutureWarning,
+                                        check_stacklevel=False) as w:
+            TimedeltaIndex([1, 3, 7], unit)
+        msg = r'.* units are deprecated .*'
+        assert re.match(msg, str(w[0].message))
+
 
 class TestTimeSeries(object):
 

pandas/tests/scalar/timedelta/test_timedelta.py

@@ -1,5 +1,7 @@
 """ test the scalar Timedelta """
 from datetime import timedelta
+import re
+import sys
 
 import numpy as np
 import pytest
@@ -317,6 +319,7 @@ def test_nat_converters(self):
         assert result.dtype.kind == 'm'
         assert result.astype('int64') == iNaT
 
+    @pytest.mark.filterwarnings("ignore:M and Y units are deprecated")
     @pytest.mark.parametrize('units, np_unit',
                              [(['Y', 'y'], 'Y'),
                               (['M'], 'M'),
@@ -376,6 +379,21 @@ def test_unit_parser(self, units, np_unit, wrapper):
             result = Timedelta('2{}'.format(unit))
             assert result == expected
 
+    @pytest.mark.skipif(sys.version_info < (3, 6),
+                        reason="requires python3.6 or higher")
+    @pytest.mark.parametrize('unit', ['Y', 'y', 'M'])
+    def test_unit_m_y_deprecated(self, unit):
+        with tm.assert_produces_warning(FutureWarning,
+                                        check_stacklevel=False) as w1:
+            Timedelta(10, unit)
+        msg = r'.* units are deprecated .*'
+        assert re.match(msg, str(w1[0].message))
+        with tm.assert_produces_warning(FutureWarning,
+                                        check_stacklevel=False) as w2:
+            to_timedelta(10, unit)
+        msg = r'.* units are deprecated .*'
+        assert re.match(msg, str(w2[0].message))
+
     def test_numeric_conversions(self):
         assert Timedelta(0) == np.timedelta64(0, 'ns')
         assert Timedelta(10) == np.timedelta64(10, 'ns')