Warn on ndarray[int] // timedelta

Closes pandas-dev#19761.

```python
In [2]: pd.DatetimeIndex(['1931', '1970', '2017']).view('i8') // pd.Timedelta(1, unit='s')
pandas-dev/bin/ipython:1: FutureWarning: Floor division between integer array and Timedelta is
deprecated. Use 'array // timedelta.value' instead.

Out[2]: array([-1230768000,           0,  1483228800])
```

Author: TomAugspurger

doc/source/timeseries.rst

@@ -308,7 +308,7 @@ We convert the ``DatetimeIndex`` to an ``int64`` array, then divide by the conve
 
 .. ipython:: python
 
-   stamps.view('int64') // pd.Timedelta(1, unit='s')
+   stamps.view('int64') // pd.Timedelta(1, unit='s').value
 
 .. _timeseries.origin:
 

doc/source/whatsnew/v0.23.0.txt

@@ -1004,6 +1004,7 @@ Deprecations
   of the ``Series`` and ``Index`` classes have been deprecated and will be
   removed in a future version (:issue:`20419`).
 - ``DatetimeIndex.offset`` is deprecated. Use ``DatetimeIndex.freq`` instead (:issue:`20716`)
+- Floor division between an integer ndarray and a :class:`Timedelta` is deprecated. Divide by :attr:`Timedelta.value` instead (:issue:`19761`)
 - Setting ``PeriodIndex.freq`` (which was not guaranteed to work correctly) is deprecated. Use :meth:`PeriodIndex.asfreq` instead (:issue:`20678`)
 - ``Index.get_duplicates()`` is deprecated and will be removed in a future version (:issue:`20239`)
 - The previous default behavior of negative indices in ``Categorical.take`` is deprecated. In a future version it will change from meaning missing values to meaning positional indices from the right. The future behavior is consistent with :meth:`Series.take` (:issue:`20664`).

pandas/_libs/tslibs/timedeltas.pyx

@@ -1,6 +1,8 @@
 # -*- coding: utf-8 -*-
 # cython: profile=False
 import collections
+import textwrap
+import warnings
 
 import sys
 cdef bint PY3 = (sys.version_info[0] >= 3)
@@ -1188,6 +1190,15 @@ class Timedelta(_Timedelta):
             if other.dtype.kind == 'm':
                 # also timedelta-like
                 return _broadcast_floordiv_td64(self.value, other, _rfloordiv)
+            elif other.dtype.kind == 'i':
+                # Backwards compatibility
+                # GH-19761
+                msg = textwrap.dedent("""\
+                Floor division between integer array and Timedelta is
+                deprecated. Use 'array // timedelta.value' instead.
+                """)
+                warnings.warn(msg, FutureWarning)
+                return other // self.value
             raise TypeError('Invalid dtype {dtype} for '
                             '{op}'.format(dtype=other.dtype,
                                           op='__floordiv__'))

pandas/tests/scalar/timedelta/test_timedelta.py

@@ -21,6 +21,18 @@ def test_arithmetic_overflow(self):
         with pytest.raises(OverflowError):
             pd.Timestamp('1700-01-01') + timedelta(days=13 * 19999)
 
+    def test_array_timedelta_floordiv(self):
+        # https://github.com/pandas-dev/pandas/issues/19761
+        ints = pd.date_range('2012-10-08', periods=4, freq='D').view('i8')
+        msg = r"Use 'array // timedelta.value'"
+        with tm.assert_produces_warning(FutureWarning) as m:
+            result = ints // pd.Timedelta(1, unit='s')
+
+        assert msg in str(m[0].message)
+        expected = np.array([1349654400, 1349740800, 1349827200, 1349913600],
+                            dtype='i8')
+        tm.assert_numpy_array_equal(result, expected)
+
     def test_ops_error_str(self):
         # GH 13624
         td = Timedelta('1 day')