ENH: Add milliseconds field support for pd.DateOffset

doc/source/user_guide/timeseries.rst

@@ -853,6 +853,9 @@ savings time. However, all :class:`DateOffset` subclasses that are an hour or sm
 The basic :class:`DateOffset` acts similar to ``dateutil.relativedelta`` (`relativedelta documentation`_)
 that shifts a date time by the corresponding calendar duration specified. The
 arithmetic operator (``+``) can be used to perform the shift.
+Multiplication (*) and subtraction are also supported. Besides arithmetic operations,
+basic :class:`DateOffset` can also be specified to replace certain component of the
+timestamp.
 
 .. ipython:: python
 
@@ -868,6 +871,8 @@ arithmetic operator (``+``) can be used to perform the shift.
    two_business_days = 2 * pd.offsets.BDay()
    friday + two_business_days
    (friday + two_business_days).day_name()
+   # Replaces "hour" component on ts
+   ts + pd.DateOffset(hour=8)
 
 Most ``DateOffsets`` have associated frequencies strings, or offset aliases, that can be passed
 into ``freq`` keyword arguments. The available date offsets and associated frequency strings can be found below:

doc/source/whatsnew/v1.5.0.rst

@@ -34,7 +34,7 @@ Other enhancements
 - :class:`StringArray` now accepts array-likes containing nan-likes (``None``, ``np.nan``) for the ``values`` parameter in its constructor in addition to strings and :attr:`pandas.NA`. (:issue:`40839`)
 - Improved the rendering of ``categories`` in :class:`CategoricalIndex` (:issue:`45218`)
 - :meth:`to_numeric` now preserves float64 arrays when downcasting would generate values not representable in float32 (:issue:`43693`)
--
+- Add ``milliseconds`` field support for :class:`~pandas.DateOffset` (:issue:`43371`)
 
 .. ---------------------------------------------------------------------------
 .. _whatsnew_150.notable_bug_fixes:

pandas/_libs/tslibs/offsets.pyx

@@ -307,8 +307,9 @@ cdef _validate_business_time(t_input):
 
 _relativedelta_kwds = {"years", "months", "weeks", "days", "year", "month",
                        "day", "weekday", "hour", "minute", "second",
-                       "microsecond", "nanosecond", "nanoseconds", "hours",
-                       "minutes", "seconds", "microseconds"}
+                       "microsecond", "millisecond", "nanosecond",
+                       "nanoseconds", "hours", "minutes", "seconds",
+                       "milliseconds", "microseconds"}
 
 
 cdef _determine_offset(kwds):
@@ -323,11 +324,17 @@ cdef _determine_offset(kwds):
 
     _kwds_use_relativedelta = ('years', 'months', 'weeks', 'days',
                                'year', 'month', 'week', 'day', 'weekday',
-                               'hour', 'minute', 'second', 'microsecond')
+                               'hour', 'minute', 'second', 'microsecond',
+                               'millisecond')
 
     use_relativedelta = False
     if len(kwds_no_nanos) > 0:
         if any(k in _kwds_use_relativedelta for k in kwds_no_nanos):
+            if "millisecond" in kwds_no_nanos:
+                raise NotImplementedError(
+                    "Using DateOffset to replace `millisecond` component in "
+                    "datetime object is not supported."
+                )
             offset = relativedelta(**kwds_no_nanos)
             use_relativedelta = True
         else:
@@ -1238,6 +1245,7 @@ class DateOffset(RelativeDeltaOffset, metaclass=OffsetMeta):
         - hours
         - minutes
         - seconds
+        - milliseconds
         - microseconds
         - nanoseconds
 
@@ -1269,6 +1277,8 @@ class DateOffset(RelativeDeltaOffset, metaclass=OffsetMeta):
     >>> ts = pd.Timestamp('2017-01-01 09:10:11')
     >>> ts + DateOffset(months=2)
     Timestamp('2017-03-01 09:10:11')
+    >>> ts + DateOffset(day=31)
+    Timestamp('2017-01-31 09:10:11')
     """
     def __setattr__(self, name, value):
         raise AttributeError("DateOffset objects are immutable.")

pandas/tests/tseries/offsets/test_offsets.py

@@ -61,6 +61,18 @@
 
 _ApplyCases = List[Tuple[BaseOffset, Dict[datetime, datetime]]]
 
+_ARITHMETIC_DATE_OFFSET = [
+    "years",
+    "months",
+    "weeks",
+    "days",
+    "hours",
+    "minutes",
+    "seconds",
+    "milliseconds",
+    "microseconds",
+]
+
 
 class TestCommon(Base):
     # executed value created by Base._get_offset
@@ -551,28 +563,144 @@ def test_mul(self):
         assert DateOffset(2) == 2 * DateOffset(1)
         assert DateOffset(2) == DateOffset(1) * 2
 
-    def test_constructor(self):
-
-        assert (self.d + DateOffset(months=2)) == datetime(2008, 3, 2)
-        assert (self.d - DateOffset(months=2)) == datetime(2007, 11, 2)
+    @pytest.mark.parametrize("relativedelta_kwd", list(liboffsets._relativedelta_kwds))
+    def test_constructor(self, relativedelta_kwd, request):
+        if relativedelta_kwd == "millisecond":
+            request.node.add_marker(
+                pytest.mark.xfail(
+                    raises=NotImplementedError,
+                    reason="Constructing DateOffset object with `millisecond` is not "
+                    "yet supported.",
+                )
+            )
+        offset = DateOffset(**{relativedelta_kwd: 2})
+        assert offset.kwds == {relativedelta_kwd: 2}
+        assert getattr(offset, relativedelta_kwd) == 2
 
+    def test_default_constructor(self):
         assert (self.d + DateOffset(2)) == datetime(2008, 1, 4)
 
+    def test_is_anchored(self):
         assert not DateOffset(2).is_anchored()
         assert DateOffset(1).is_anchored()
 
-        d = datetime(2008, 1, 31)
-        assert (d + DateOffset(months=1)) == datetime(2008, 2, 29)
-
     def test_copy(self):
         assert DateOffset(months=2).copy() == DateOffset(months=2)
+        assert DateOffset(milliseconds=1).copy() == DateOffset(milliseconds=1)
+
+    @pytest.mark.parametrize(
+        "arithmatic_offset_type, expected",
+        zip(
+            _ARITHMETIC_DATE_OFFSET,
+            [
+                "2009-01-02",
+                "2008-02-02",
+                "2008-01-09",
+                "2008-01-03",
+                "2008-01-02 01:00:00",
+                "2008-01-02 00:01:00",
+                "2008-01-02 00:00:01",
+                "2008-01-02 00:00:00.001000000",
+                "2008-01-02 00:00:00.000001000",
+            ],
+        ),
+    )
+    def test_add(self, arithmatic_offset_type, expected):
+        assert DateOffset(**{arithmatic_offset_type: 1}) + self.d == Timestamp(expected)
+        assert self.d + DateOffset(**{arithmatic_offset_type: 1}) == Timestamp(expected)
+
+    @pytest.mark.parametrize(
+        "arithmatic_offset_type, expected",
+        zip(
+            _ARITHMETIC_DATE_OFFSET,
+            [
+                "2007-01-02",
+                "2007-12-02",
+                "2007-12-26",
+                "2008-01-01",
+                "2008-01-01 23:00:00",
+                "2008-01-01 23:59:00",
+                "2008-01-01 23:59:59",
+                "2008-01-01 23:59:59.999000000",
+                "2008-01-01 23:59:59.999999000",
+            ],
+        ),
+    )
+    def test_sub(self, arithmatic_offset_type, expected):
+        assert self.d - DateOffset(**{arithmatic_offset_type: 1}) == Timestamp(expected)
+        with pytest.raises(TypeError, match="Cannot subtract datetime from offset"):
+            DateOffset(**{arithmatic_offset_type: 1}) - self.d
+
+    @pytest.mark.parametrize(
+        "arithmatic_offset_type, n, expected",
+        zip(
+            _ARITHMETIC_DATE_OFFSET,
+            range(1, 10),
+            [
+                "2009-01-02",
+                "2008-03-02",
+                "2008-01-23",
+                "2008-01-06",
+                "2008-01-02 05:00:00",
+                "2008-01-02 00:06:00",
+                "2008-01-02 00:00:07",
+                "2008-01-02 00:00:00.008000000",
+                "2008-01-02 00:00:00.000009000",
+            ],
+        ),
+    )
+    def test_mul_add(self, arithmatic_offset_type, n, expected):
+        assert DateOffset(**{arithmatic_offset_type: 1}) * n + self.d == Timestamp(
+            expected
+        )
+        assert n * DateOffset(**{arithmatic_offset_type: 1}) + self.d == Timestamp(
+            expected
+        )
+        assert self.d + DateOffset(**{arithmatic_offset_type: 1}) * n == Timestamp(
+            expected
+        )
+        assert self.d + n * DateOffset(**{arithmatic_offset_type: 1}) == Timestamp(
+            expected
+        )
+
+    @pytest.mark.parametrize(
+        "arithmatic_offset_type, n, expected",
+        zip(
+            _ARITHMETIC_DATE_OFFSET,
+            range(1, 10),
+            [
+                "2007-01-02",
+                "2007-11-02",
+                "2007-12-12",
+                "2007-12-29",
+                "2008-01-01 19:00:00",
+                "2008-01-01 23:54:00",
+                "2008-01-01 23:59:53",
+                "2008-01-01 23:59:59.992000000",
+                "2008-01-01 23:59:59.999991000",
+            ],
+        ),
+    )
+    def test_mul_sub(self, arithmatic_offset_type, n, expected):
+        assert self.d - DateOffset(**{arithmatic_offset_type: 1}) * n == Timestamp(
+            expected
+        )
+        assert self.d - n * DateOffset(**{arithmatic_offset_type: 1}) == Timestamp(
+            expected
+        )
+
+    def test_leap_year(self):
+        d = datetime(2008, 1, 31)
+        assert (d + DateOffset(months=1)) == datetime(2008, 2, 29)
 
     def test_eq(self):
         offset1 = DateOffset(days=1)
         offset2 = DateOffset(days=365)
 
         assert offset1 != offset2
 
+        assert DateOffset(milliseconds=3) != DateOffset(milliseconds=7)
+
 
 class TestOffsetNames:
     def test_get_offset_name(self):
@@ -741,7 +869,15 @@ def test_month_offset_name(month_classes):
 
 
 @pytest.mark.parametrize("kwd", sorted(liboffsets._relativedelta_kwds))
-def test_valid_relativedelta_kwargs(kwd):
+def test_valid_relativedelta_kwargs(kwd, request):
+    if kwd == "millisecond":
+        request.node.add_marker(
+            pytest.mark.xfail(
+                raises=NotImplementedError,
+                reason="Constructing DateOffset object with `millisecond` is not "
+                "yet supported.",
+            )
+        )
     # Check that all the arguments specified in liboffsets._relativedelta_kwds
     # are in fact valid relativedelta keyword args
     DateOffset(**{kwd: 1})