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

doc/source/whatsnew/v0.24.0.txt

@@ -514,6 +514,8 @@ Deprecations
 - The signature of :meth:`Series.to_csv` has been uniformed to that of doc:meth:`DataFrame.to_csv`: the name of the first argument is now 'path_or_buf', the order of subsequent arguments has changed, the 'header' argument now defaults to True. (:issue:`19715`)
 - :meth:`Categorical.from_codes` has deprecated providing float values for the ``codes`` argument. (:issue:`21767`)
 - :func:`pandas.read_table` is deprecated. Instead, use :func:`pandas.read_csv` passing ``sep='\t'`` if necessary (:issue:`21948`)
+- 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,14 @@ 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 version "
+                              "0.26.0 (or 1.0, whichever comes first).  "
+                              "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 +1680,14 @@ 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 version "
+                              "0.26.0 (or 1.0, whichever comes first).  "
+                              "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):

pandas/_libs/tslibs/timestamps.pyx

@@ -250,14 +250,24 @@ 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 version "
+                              "0.26.0 (or 1.0, whichever comes first).  "
+                              "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,15 @@ 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
+            warnings.warn("Addition/subtraction of integer array from {cls} "
+                          "is deprecated, will be removed in version "
+                          "0.26.0 (or 1.0, whichever comes first).  "
+                          "Instead of adding `arr`, add `arr * self.freq`"
+                          .format(cls=type(self).__name__), FutureWarning)
+
         if is_period_dtype(self):
             # easy case for PeriodIndex
             if op is operator.sub:
@@ -584,6 +593,14 @@ 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
+                    warnings.warn("Addition of integers to {cls} is "
+                                  "deprecated, will be removed in version "
+                                  "0.26.0 (or 1.0, whichever comes first).  "
+                                  "Instead of adding `n`, add `n * self.freq`"
+                                  .format(cls=type(self).__name__),
+                                  FutureWarning)
                 result = self.shift(other)
 
             # array-like others
@@ -636,6 +653,15 @@ 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
+                    warnings.warn("Subtraction of integers from {cls} is "
+                                  "deprecated, will be removed in version "
+                                  "0.26.0 (or 1.0, whichever comes first).  "
+                                  "Instead of subtracting `n`, subtract "
+                                  "`n * self.freq`"
+                                  .format(cls=type(self).__name__),
+                                  FutureWarning)
                 result = self.shift(-other)
             elif isinstance(other, Period):
                 result = self._sub_period(other)