DEPR: deprecate integer add/sub with DTI/TDI/PI/Timestamp/Period

doc/source/whatsnew/v0.24.0.txt

@@ -556,6 +556,8 @@ Deprecations
 - :func:`pandas.read_table` is deprecated. Instead, use :func:`pandas.read_csv` passing ``sep='\t'`` if necessary (:issue:`21948`)
 - :meth:`Series.str.cat` has deprecated using arbitrary list-likes *within* list-likes. A list-like container may still contain
   many ``Series``, ``Index`` or 1-dimensional ``np.ndarray``, or alternatively, only scalar values. (:issue:`21950`)
+- Addition or subtraction of integers with :class:`Timestamp`, :class:`Period`, :class:`DatetimeIndex`, :class:`TimedeltaIndex`, :class:`PeriodIndex` is deprecated, will be removed in a future version (:issue:`21939`)
+- Addition or subtraction of integer-dtyped arrays with :class:`DatetimeIndex`, :class:`TimedeltaIndex`, :class:`PeriodIndex` is deprecated, will be removed in a future version (:issue:`21939`)
 
 .. _whatsnew_0240.prior_deprecations:
 

pandas/_libs/tslibs/period.pyx

@@ -1,5 +1,6 @@
 # -*- coding: utf-8 -*-
 from datetime import datetime, date
+import warnings
 
 from cpython cimport (
     PyUnicode_Check,
@@ -1645,6 +1646,13 @@ cdef class _Period(object):
             elif other is NaT:
                 return NaT
             elif util.is_integer_object(other):
+                warnings.warn("Addition of integers to {cls} is "
+                              "deprecated, will be removed in a future "
+                              "version.  Instead of adding `n`, add "
+                              "`n * self.freq`"
+                              .format(cls=type(self).__name__),
+                              FutureWarning)
+
                 ordinal = self.ordinal + other * self.freq.n
                 return Period(ordinal=ordinal, freq=self.freq)
             elif (PyDateTime_Check(other) or
@@ -1671,6 +1679,13 @@ cdef class _Period(object):
                 neg_other = -other
                 return self + neg_other
             elif util.is_integer_object(other):
+                warnings.warn("Subtraction of integers from {cls} is "
+                              "deprecated, will be removed in a future "
+                              "version.  Instead of subtracting `n`, subtract "
+                              "`n * self.freq`"
+                              .format(cls=type(self).__name__),
+                              FutureWarning)
+
                 ordinal = self.ordinal - other * self.freq.n
                 return Period(ordinal=ordinal, freq=self.freq)
             elif is_period_object(other):
@@ -1756,7 +1771,7 @@ cdef class _Period(object):
     def end_time(self):
         # freq.n can't be negative or 0
         # ordinal = (self + self.freq.n).start_time.value - 1
-        ordinal = (self + 1).start_time.value - 1
+        ordinal = (self + self.freq).start_time.value - 1
         return Timestamp(ordinal)
 
     def to_timestamp(self, freq=None, how='start', tz=None):
@@ -1783,7 +1798,8 @@ cdef class _Period(object):
 
         end = how == 'E'
         if end:
-            return (self + 1).to_timestamp(how='start') - Timedelta(1, 'ns')
+            endpoint = (self + self.freq).to_timestamp(how='start')
+            return endpoint - Timedelta(1, 'ns')
 
         if freq is None:
             base, mult = get_freq_code(self.freq)

pandas/_libs/tslibs/timestamps.pyx

@@ -250,14 +250,23 @@ cdef class _Timestamp(datetime):
         return np.datetime64(self.value, 'ns')
 
     def __add__(self, other):
-        cdef int64_t other_int, nanos
+        cdef:
+            int64_t other_int, nanos
 
         if is_timedelta64_object(other):
             other_int = other.astype('timedelta64[ns]').view('i8')
             return Timestamp(self.value + other_int,
                              tz=self.tzinfo, freq=self.freq)
 
         elif is_integer_object(other):
+            if self.freq is None:
+                warnings.warn("Addition of integers to {cls} is "
+                              "deprecated, will be removed in a future "
+                              "version.  Instead of adding `n`, add "
+                              "`n * self.freq`"
+                              .format(cls=type(self).__name__),
+                              FutureWarning)
+
             if self is NaT:
                 # to be compat with Period
                 return NaT

pandas/core/arrays/datetimelike.py

@@ -466,6 +466,18 @@ def _addsub_int_array(self, other, op):
         result : same class as self
         """
         assert op in [operator.add, operator.sub]
+
+        if self.freq is not None:
+            # case with freq of None will raise
+            # we need to use a different stacklevel for Index vs Array
+            lvl = 3 + 1 * isinstance(self, ABCIndexClass)
+            warnings.warn("Addition/subtraction of integer array from {cls} "
+                          "is deprecated, will be removed in a future "
+                          "version.  Instead of adding `arr`, "
+                          "add `arr * self.freq`"
+                          .format(cls=type(self).__name__),
+                          FutureWarning, stacklevel=lvl)
+
         if is_period_dtype(self):
             # easy case for PeriodIndex
             if op is operator.sub:
@@ -584,6 +596,16 @@ def __add__(self, other):
             elif lib.is_integer(other):
                 # This check must come after the check for np.timedelta64
                 # as is_integer returns True for these
+                if self.freq is not None:
+                    # case with freq of None will raise
+                    # we need to use a different stacklevel for Index vs Array
+                    lvl = 2 + 1 * isinstance(self, ABCIndexClass)
+                    warnings.warn("Addition of integers to {cls} is "
+                                  "deprecated, will be removed in a future "
+                                  "version.  Instead of adding `n`, "
+                                  "add `n * self.freq`"
+                                  .format(cls=type(self).__name__),
+                                  FutureWarning, stacklevel=lvl)
                 result = self.shift(other)
 
             # array-like others
@@ -636,6 +658,16 @@ def __sub__(self, other):
             elif lib.is_integer(other):
                 # This check must come after the check for np.timedelta64
                 # as is_integer returns True for these
+                if self.freq is not None:
+                    # case with freq of None will raise
+                    # we need to use a different stacklevel for Index vs Array
+                    lvl = 2 + 1 * isinstance(self, ABCIndexClass)
+                    warnings.warn("Subtraction of integers from {cls} is "
+                                  "deprecated, will be removed in a future "
+                                  "version.  Instead of subtracting `n`, "
+                                  "subtract `n * self.freq`"
+                                  .format(cls=type(self).__name__),
+                                  FutureWarning, stacklevel=lvl)
                 result = self.shift(-other)
             elif isinstance(other, Period):
                 result = self._sub_period(other)

pandas/core/resample.py

@@ -1426,7 +1426,7 @@ def _get_time_delta_bins(self, ax):
                                          freq=self.freq,
                                          name=ax.name)
 
-        end_stamps = labels + 1
+        end_stamps = labels + self.freq
         bins = ax.searchsorted(end_stamps, side='left')
 
         # Addresses GH #10530

pandas/plotting/_converter.py

@@ -583,7 +583,7 @@ def period_break(dates, period):
         Name of the period to monitor.
     """
     current = getattr(dates, period)
-    previous = getattr(dates - 1, period)
+    previous = getattr(dates - 1 * dates.freq, period)
     return np.nonzero(current - previous)[0]
 
 
@@ -669,7 +669,7 @@ def first_label(label_flags):
 
         def _hour_finder(label_interval, force_year_start):
             _hour = dates_.hour
-            _prev_hour = (dates_ - 1).hour
+            _prev_hour = (dates_ - 1 * dates_.freq).hour
             hour_start = (_hour - _prev_hour) != 0
             info_maj[day_start] = True
             info_min[hour_start & (_hour % label_interval == 0)] = True
@@ -683,7 +683,7 @@ def _hour_finder(label_interval, force_year_start):
         def _minute_finder(label_interval):
             hour_start = period_break(dates_, 'hour')
             _minute = dates_.minute
-            _prev_minute = (dates_ - 1).minute
+            _prev_minute = (dates_ - 1 * dates_.freq).minute
             minute_start = (_minute - _prev_minute) != 0
             info_maj[hour_start] = True
             info_min[minute_start & (_minute % label_interval == 0)] = True
@@ -696,7 +696,7 @@ def _minute_finder(label_interval):
         def _second_finder(label_interval):
             minute_start = period_break(dates_, 'minute')
             _second = dates_.second
-            _prev_second = (dates_ - 1).second
+            _prev_second = (dates_ - 1 * dates_.freq).second
             second_start = (_second - _prev_second) != 0
             info['maj'][minute_start] = True
             info['min'][second_start & (_second % label_interval == 0)] = True

pandas/tests/arithmetic/test_datetime64.py

@@ -1035,7 +1035,8 @@ def test_dti_add_int(self, tz_naive_fixture, one):
         tz = tz_naive_fixture
         rng = pd.date_range('2000-01-01 09:00', freq='H',
                             periods=10, tz=tz)
-        result = rng + one
+        with tm.assert_produces_warning(FutureWarning, check_stacklevel=False):
+            result = rng + one
         expected = pd.date_range('2000-01-01 10:00', freq='H',
                                  periods=10, tz=tz)
         tm.assert_index_equal(result, expected)
@@ -1046,14 +1047,16 @@ def test_dti_iadd_int(self, tz_naive_fixture, one):
                             periods=10, tz=tz)
         expected = pd.date_range('2000-01-01 10:00', freq='H',
                                  periods=10, tz=tz)
-        rng += one
+        with tm.assert_produces_warning(FutureWarning, check_stacklevel=False):
+            rng += one
         tm.assert_index_equal(rng, expected)
 
     def test_dti_sub_int(self, tz_naive_fixture, one):
         tz = tz_naive_fixture
         rng = pd.date_range('2000-01-01 09:00', freq='H',
                             periods=10, tz=tz)
-        result = rng - one
+        with tm.assert_produces_warning(FutureWarning, check_stacklevel=False):
+            result = rng - one
         expected = pd.date_range('2000-01-01 08:00', freq='H',
                                  periods=10, tz=tz)
         tm.assert_index_equal(result, expected)
@@ -1064,7 +1067,8 @@ def test_dti_isub_int(self, tz_naive_fixture, one):
                             periods=10, tz=tz)
         expected = pd.date_range('2000-01-01 08:00', freq='H',
                                  periods=10, tz=tz)
-        rng -= one
+        with tm.assert_produces_warning(FutureWarning, check_stacklevel=False):
+            rng -= one
         tm.assert_index_equal(rng, expected)
 
     # -------------------------------------------------------------
@@ -1077,9 +1081,11 @@ def test_dti_add_intarray_tick(self, box, freq):
         dti = pd.date_range('2016-01-01', periods=2, freq=freq)
         other = box([4, -1])
         expected = DatetimeIndex([dti[n] + other[n] for n in range(len(dti))])
-        result = dti + other
+        with tm.assert_produces_warning(FutureWarning, check_stacklevel=False):
+            result = dti + other
         tm.assert_index_equal(result, expected)
-        result = other + dti
+        with tm.assert_produces_warning(FutureWarning, check_stacklevel=False):
+            result = other + dti
         tm.assert_index_equal(result, expected)
 
     @pytest.mark.parametrize('freq', ['W', 'M', 'MS', 'Q'])
@@ -1089,10 +1095,17 @@ def test_dti_add_intarray_non_tick(self, box, freq):
         dti = pd.date_range('2016-01-01', periods=2, freq=freq)
         other = box([4, -1])
         expected = DatetimeIndex([dti[n] + other[n] for n in range(len(dti))])
-        with tm.assert_produces_warning(PerformanceWarning):
+
+        # tm.assert_produces_warning does not handle cases where we expect
+        # two warnings, in this case PerformanceWarning and FutureWarning.
+        # Until that is fixed, we don't catch either
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore")
             result = dti + other
         tm.assert_index_equal(result, expected)
-        with tm.assert_produces_warning(PerformanceWarning):
+
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore")
             result = other + dti
         tm.assert_index_equal(result, expected)
 
@@ -1637,13 +1650,15 @@ def test_dti_add_offset_array(self, tz_naive_fixture):
         dti = pd.date_range('2017-01-01', periods=2, tz=tz)
         other = np.array([pd.offsets.MonthEnd(), pd.offsets.Day(n=2)])
 
-        with tm.assert_produces_warning(PerformanceWarning):
+        with tm.assert_produces_warning(PerformanceWarning,
+                                        clear=[pd.core.arrays.datetimelike]):
             res = dti + other
         expected = DatetimeIndex([dti[n] + other[n] for n in range(len(dti))],
                                  name=dti.name, freq='infer')
         tm.assert_index_equal(res, expected)
 
-        with tm.assert_produces_warning(PerformanceWarning):
+        with tm.assert_produces_warning(PerformanceWarning,
+                                        clear=[pd.core.arrays.datetimelike]):
             res2 = other + dti
         tm.assert_index_equal(res2, expected)
 
@@ -1657,13 +1672,15 @@ def test_dti_add_offset_index(self, tz_naive_fixture, names):
         other = pd.Index([pd.offsets.MonthEnd(), pd.offsets.Day(n=2)],
                          name=names[1])
 
-        with tm.assert_produces_warning(PerformanceWarning):
+        with tm.assert_produces_warning(PerformanceWarning,
+                                        clear=[pd.core.arrays.datetimelike]):
             res = dti + other
         expected = DatetimeIndex([dti[n] + other[n] for n in range(len(dti))],
                                  name=names[2], freq='infer')
         tm.assert_index_equal(res, expected)
 
-        with tm.assert_produces_warning(PerformanceWarning):
+        with tm.assert_produces_warning(PerformanceWarning,
+                                        clear=[pd.core.arrays.datetimelike]):
             res2 = other + dti
         tm.assert_index_equal(res2, expected)
 
@@ -1673,7 +1690,8 @@ def test_dti_sub_offset_array(self, tz_naive_fixture):
         dti = pd.date_range('2017-01-01', periods=2, tz=tz)
         other = np.array([pd.offsets.MonthEnd(), pd.offsets.Day(n=2)])
 
-        with tm.assert_produces_warning(PerformanceWarning):
+        with tm.assert_produces_warning(PerformanceWarning,
+                                        clear=[pd.core.arrays.datetimelike]):
             res = dti - other
         expected = DatetimeIndex([dti[n] - other[n] for n in range(len(dti))],
                                  name=dti.name, freq='infer')
@@ -1689,7 +1707,8 @@ def test_dti_sub_offset_index(self, tz_naive_fixture, names):
         other = pd.Index([pd.offsets.MonthEnd(), pd.offsets.Day(n=2)],
                          name=names[1])
 
-        with tm.assert_produces_warning(PerformanceWarning):
+        with tm.assert_produces_warning(PerformanceWarning,
+                                        clear=[pd.core.arrays.datetimelike]):
             res = dti - other
         expected = DatetimeIndex([dti[n] - other[n] for n in range(len(dti))],
                                  name=names[2], freq='infer')
@@ -1708,18 +1727,21 @@ def test_dti_with_offset_series(self, tz_naive_fixture, names):
         expected_add = Series([dti[n] + other[n] for n in range(len(dti))],
                               name=names[2])
 
-        with tm.assert_produces_warning(PerformanceWarning):
+        with tm.assert_produces_warning(PerformanceWarning,
+                                        clear=[pd.core.arrays.datetimelike]):
             res = dti + other
         tm.assert_series_equal(res, expected_add)
 
-        with tm.assert_produces_warning(PerformanceWarning):
+        with tm.assert_produces_warning(PerformanceWarning,
+                                        clear=[pd.core.arrays.datetimelike]):
             res2 = other + dti
         tm.assert_series_equal(res2, expected_add)
 
         expected_sub = Series([dti[n] - other[n] for n in range(len(dti))],
                               name=names[2])
 
-        with tm.assert_produces_warning(PerformanceWarning):
+        with tm.assert_produces_warning(PerformanceWarning,
+                                        clear=[pd.core.arrays.datetimelike]):
             res3 = dti - other
         tm.assert_series_equal(res3, expected_sub)
 
@@ -1755,7 +1777,8 @@ def test_dt64_with_offset_array(klass, assert_func):
     # GH#10699
     # array of offsets
     box = Series if klass is Series else pd.Index
-    with tm.assert_produces_warning(PerformanceWarning):
+    with tm.assert_produces_warning(PerformanceWarning,
+                                    clear=[pd.core.arrays.datetimelike]):
         s = klass([Timestamp('2000-1-1'), Timestamp('2000-2-1')])
         result = s + box([pd.offsets.DateOffset(years=1),
                           pd.offsets.MonthEnd()])