ENH: implement Timedelta.__mod__ and __divmod__ (#19755)

Author: jbrockmendel

doc/source/timedeltas.rst

@@ -283,6 +283,20 @@ Rounded division (floor-division) of a ``timedelta64[ns]`` Series by a scalar
    td // pd.Timedelta(days=3, hours=4)
    pd.Timedelta(days=3, hours=4) // td
 
+.. _timedeltas.mod_divmod:
+
+The mod (%) and divmod operations are defined for ``Timedelta`` when operating with another timedelta-like or with a numeric argument.
+
+.. ipython:: python
+
+   pd.Timedelta(hours=37) % datetime.timedelta(hours=2)
+
+   # divmod against a timedelta-like returns a pair (int, Timedelta)
+   divmod(datetime.timedelta(hours=2), pd.Timedelta(minutes=11))
+
+   # divmod against a numeric returns a pair (Timedelta, Timedelta)
+   divmod(pd.Timedelta(hours=25), 86400000000000)
+
 Attributes
 ----------
 

doc/source/whatsnew/v0.23.0.txt

@@ -117,6 +117,20 @@ resetting indexes. See the :ref:`Sorting by Indexes and Values
    # Sort by 'second' (index) and 'A' (column)
    df_multi.sort_values(by=['second', 'A'])
 
+.. _whatsnew_0230.enhancements.timedelta_mod
+
+Timedelta mod method
+^^^^^^^^^^^^^^^^^^^^
+
+``mod`` (%) and ``divmod`` operations are now defined on ``Timedelta`` objects
+when operating with either timedelta-like or with numeric arguments.
+See the :ref:`documentation here <timedeltas.mod_divmod>`. (:issue:`19365`)
+
+.. ipython:: python
+
+    td = pd.Timedelta(hours=37)
+    td % pd.Timedelta(minutes=45)
+
 .. _whatsnew_0230.enhancements.ran_inf:
 
 ``.rank()`` handles ``inf`` values when ``NaN`` are present

pandas/_libs/tslibs/timedeltas.pyx

@@ -1149,6 +1149,24 @@ class Timedelta(_Timedelta):
             return np.nan
         return other.value // self.value
 
+    def __mod__(self, other):
+        # Naive implementation, room for optimization
+        return self.__divmod__(other)[1]
+
+    def __rmod__(self, other):
+        # Naive implementation, room for optimization
+        return self.__rdivmod__(other)[1]
+
+    def __divmod__(self, other):
+        # Naive implementation, room for optimization
+        div = self // other
+        return div, self - div * other
+
+    def __rdivmod__(self, other):
+        # Naive implementation, room for optimization
+        div = other // self
+        return div, other - div * self
+
 
 cdef _floordiv(int64_t value, right):
     return value // right

pandas/tests/scalar/timedelta/test_arithmetic.py

@@ -420,3 +420,189 @@ def test_td_rfloordiv_numeric_series(self):
         assert res is NotImplemented
         with pytest.raises(TypeError):
             ser // td
+
+    def test_mod_timedeltalike(self):
+        # GH#19365
+        td = Timedelta(hours=37)
+
+        # Timedelta-like others
+        result = td % Timedelta(hours=6)
+        assert isinstance(result, Timedelta)
+        assert result == Timedelta(hours=1)
+
+        result = td % timedelta(minutes=60)
+        assert isinstance(result, Timedelta)
+        assert result == Timedelta(0)
+
+        result = td % NaT
+        assert result is NaT
+
+    @pytest.mark.xfail(reason='GH#19378 floordiv td64 returns td64')
+    def test_mod_timedelta64_nat(self):
+        # GH#19365
+        td = Timedelta(hours=37)
+
+        result = td % np.timedelta64('NaT', 'ns')
+        assert result is NaT
+
+    @pytest.mark.xfail(reason='GH#19378 floordiv td64 returns td64')
+    def test_mod_timedelta64(self):
+        # GH#19365
+        td = Timedelta(hours=37)
+
+        result = td % np.timedelta64(2, 'h')
+        assert isinstance(result, Timedelta)
+        assert result == Timedelta(hours=1)
+
+    @pytest.mark.xfail(reason='GH#19378 floordiv by Tick not implemented')
+    def test_mod_offset(self):
+        # GH#19365
+        td = Timedelta(hours=37)
+
+        result = td % pd.offsets.Hour(5)
+        assert isinstance(result, Timedelta)
+        assert result == Timedelta(hours=2)
+
+    # ----------------------------------------------------------------
+    # Timedelta.__mod__, __rmod__
+
+    def test_mod_numeric(self):
+        # GH#19365
+        td = Timedelta(hours=37)
+
+        # Numeric Others
+        result = td % 2
+        assert isinstance(result, Timedelta)
+        assert result == Timedelta(0)
+
+        result = td % 1e12
+        assert isinstance(result, Timedelta)
+        assert result == Timedelta(minutes=3, seconds=20)
+
+        result = td % int(1e12)
+        assert isinstance(result, Timedelta)
+        assert result == Timedelta(minutes=3, seconds=20)
+
+    def test_mod_invalid(self):
+        # GH#19365
+        td = Timedelta(hours=37)
+
+        with pytest.raises(TypeError):
+            td % pd.Timestamp('2018-01-22')
+
+        with pytest.raises(TypeError):
+            td % []
+
+    def test_rmod_pytimedelta(self):
+        # GH#19365
+        td = Timedelta(minutes=3)
+
+        result = timedelta(minutes=4) % td
+        assert isinstance(result, Timedelta)
+        assert result == Timedelta(minutes=1)
+
+    @pytest.mark.xfail(reason='GH#19378 floordiv by Tick not implemented')
+    def test_rmod_timedelta64(self):
+        # GH#19365
+        td = Timedelta(minutes=3)
+        result = np.timedelta64(5, 'm') % td
+        assert isinstance(result, Timedelta)
+        assert result == Timedelta(minutes=2)
+
+    def test_rmod_invalid(self):
+        # GH#19365
+        td = Timedelta(minutes=3)
+
+        with pytest.raises(TypeError):
+            pd.Timestamp('2018-01-22') % td
+
+        with pytest.raises(TypeError):
+            15 % td
+
+        with pytest.raises(TypeError):
+            16.0 % td
+
+        with pytest.raises(TypeError):
+            np.array([22, 24]) % td
+
+    # ----------------------------------------------------------------
+    # Timedelta.__divmod__, __rdivmod__
+
+    def test_divmod_numeric(self):
+        # GH#19365
+        td = Timedelta(days=2, hours=6)
+
+        result = divmod(td, 53 * 3600 * 1e9)
+        assert result[0] == Timedelta(1, unit='ns')
+        assert isinstance(result[1], Timedelta)
+        assert result[1] == Timedelta(hours=1)
+
+        assert result
+        result = divmod(td, np.nan)
+        assert result[0] is pd.NaT
+        assert result[1] is pd.NaT
+
+    def test_divmod(self):
+        # GH#19365
+        td = Timedelta(days=2, hours=6)
+
+        result = divmod(td, timedelta(days=1))
+        assert result[0] == 2
+        assert isinstance(result[1], Timedelta)
+        assert result[1] == Timedelta(hours=6)
+
+        result = divmod(td, 54)
+        assert result[0] == Timedelta(hours=1)
+        assert isinstance(result[1], Timedelta)
+        assert result[1] == Timedelta(0)
+
+        result = divmod(td, pd.NaT)
+        assert np.isnan(result[0])
+        assert result[1] is pd.NaT
+
+    @pytest.mark.xfail(reason='GH#19378 floordiv by Tick not implemented')
+    def test_divmod_offset(self):
+        # GH#19365
+        td = Timedelta(days=2, hours=6)
+
+        result = divmod(td, pd.offsets.Hour(-4))
+        assert result[0] == -14
+        assert isinstance(result[1], Timedelta)
+        assert result[1] == Timedelta(hours=-2)
+
+    def test_divmod_invalid(self):
+        # GH#19365
+        td = Timedelta(days=2, hours=6)
+
+        with pytest.raises(TypeError):
+            divmod(td, pd.Timestamp('2018-01-22'))
+
+    def test_rdivmod_pytimedelta(self):
+        # GH#19365
+        result = divmod(timedelta(days=2, hours=6), Timedelta(days=1))
+        assert result[0] == 2
+        assert isinstance(result[1], Timedelta)
+        assert result[1] == Timedelta(hours=6)
+
+    @pytest.mark.xfail(reason='GH#19378 floordiv by Tick not implemented')
+    def test_rdivmod_offset(self):
+        result = divmod(pd.offsets.Hour(54), Timedelta(hours=-4))
+        assert result[0] == -14
+        assert isinstance(result[1], Timedelta)
+        assert result[1] == Timedelta(hours=-2)
+
+    def test_rdivmod_invalid(self):
+        # GH#19365
+        td = Timedelta(minutes=3)
+
+        with pytest.raises(TypeError):
+            divmod(pd.Timestamp('2018-01-22'), td)
+
+        with pytest.raises(TypeError):
+            divmod(15, td)
+
+        with pytest.raises(TypeError):
+            divmod(16.0, td)
+
+        with pytest.raises(TypeError):
+            divmod(np.array([22, 24]), td)