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

doc/source/whatsnew/v0.24.0.txt

@@ -575,6 +575,57 @@ Deprecations
 - :meth:`FrozenNDArray.searchsorted` has deprecated the ``v`` parameter in favor of ``value`` (:issue:`14645`)
 - :func:`DatetimeIndex.shift` now accepts ``periods`` argument instead of ``n`` for consistency with :func:`Index.shift` and :func:`Series.shift`. Using ``n`` throws a deprecation warning (:issue:`22458`)
 
+.. _whatsnew_0240.deprecations.datetimelike_int_ops:
+
+Integer Addition/Subtraction with Datetime-like Classes Is Deprecated
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+In the past, users could add or subtract integers or integer-dtypes arrays
+from :class:`Period`, :class:`PeriodIndex`, and in some cases
+:class:`Timestamp`, :class:`DatetimeIndex` and :class:`TimedeltaIndex`.
+
+This usage is now deprecated.  Instead add or subtract integer multiples of
+the object's ``freq`` attribute (:issue:`21939`)
+
+Previous Behavior:
+
+.. code-block:: ipython
+
+    In [3]: per = pd.Period('2016Q1')
+    In [4]: per + 3
+    Out[4]: Period('2016Q4', 'Q-DEC')
+
+    In [5]: ts = pd.Timestamp('1994-05-06 12:15:16', freq=pd.offsets.Hour())
+    In [6]: ts + 2
+    Out[6]: Timestamp('1994-05-06 14:15:16', freq='H')
+
+    In [7]: tdi = pd.timedelta_range('1D', periods=2)
+    In [8]: tdi - np.array([2, 1])
+    Out[8]: TimedeltaIndex(['-1 days', '1 days'], dtype='timedelta64[ns]', freq=None)
+
+    In [9]: dti = pd.date_range('2001-01-01', periods=2, freq='7D')
+    In [10]: dti + pd.Index([1, 2])
+    Out[10]: DatetimeIndex(['2001-01-08', '2001-01-22'], dtype='datetime64[ns]', freq=None)
+
+Current Behavior:
+
+.. ipython:: python
+
+    In [3]: per = pd.Period('2016Q1')
+    In [4]: per + 3 * per.freq
+    Out[4]: Period('2016Q4', 'Q-DEC')
+
+    In [5]: ts = pd.Timestamp('1994-05-06 12:15:16', freq=pd.offsets.Hour())
+    In [6]: ts + 2 * ts.freq
+    Out[6]: Timestamp('1994-05-06 14:15:16', freq='H')
+
+    In [7]: tdi = pd.timedelta_range('1D', periods=2)
+    In [8]: tdi - np.array([2 * tdi.freq, 1 * tdi.freq])
+    Out[8]: TimedeltaIndex(['-1 days', '1 days'], dtype='timedelta64[ns]', freq=None)
+
+    In [9]: dti = pd.date_range('2001-01-01', periods=2, freq='7D')
+    In [10]: dti + pd.Index([1 * dti.freq, 2 * dti.freq])
+    Out[10]: DatetimeIndex(['2001-01-08', '2001-01-22'], dtype='datetime64[ns]', freq=None)
+
 .. _whatsnew_0240.prior_deprecations:
 
 Removal of prior version deprecations/changes

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 not 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

@@ -468,6 +468,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:
@@ -600,6 +612,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
@@ -652,6 +674,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

@@ -1425,7 +1425,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