From bd7f8cfc51d72bd7de959b8b3a66d03487cd5905 Mon Sep 17 00:00:00 2001 From: Brock Mendel Date: Thu, 25 Jan 2018 11:15:30 -0800 Subject: [PATCH 1/4] Fix invalid relativedelta_kwds --- pandas/_libs/tslibs/offsets.pyx | 4 ++-- pandas/tests/tseries/offsets/test_offsets.py | 7 +++++++ 2 files changed, 9 insertions(+), 2 deletions(-) diff --git a/pandas/_libs/tslibs/offsets.pyx b/pandas/_libs/tslibs/offsets.pyx index a0ac6389c0646..fad97e7f83896 100644 --- a/pandas/_libs/tslibs/offsets.pyx +++ b/pandas/_libs/tslibs/offsets.pyx @@ -243,10 +243,10 @@ def _validate_business_time(t_input): relativedelta_kwds = set([ 'years', 'months', 'weeks', 'days', - 'year', 'month', 'week', 'day', 'weekday', + 'year', 'month', 'day', 'weekday', 'hour', 'minute', 'second', 'microsecond', 'nanosecond', 'nanoseconds', - 'hours', 'minutes', 'seconds', 'milliseconds', 'microseconds']) + 'hours', 'minutes', 'seconds', 'microseconds']) def _determine_offset(kwds): diff --git a/pandas/tests/tseries/offsets/test_offsets.py b/pandas/tests/tseries/offsets/test_offsets.py index b086884ecd250..7d5678b27b104 100644 --- a/pandas/tests/tseries/offsets/test_offsets.py +++ b/pandas/tests/tseries/offsets/test_offsets.py @@ -3103,6 +3103,13 @@ def test_valid_month_attributes(kwd, month_classes): cls(**{kwd: 3}) +@pytest.mark.parametrize('kwd', sorted(list(liboffsets.relativedelta_kwds))) +def test_valid_relativedelta_kwargs(kwd): + # Check that all the arguments specified in liboffsets.relativedelta_kwds + # are in fact valid relativedelta keyword args + DateOffset(**{kwd: 1}) + + @pytest.mark.parametrize('kwd', sorted(list(liboffsets.relativedelta_kwds))) def test_valid_tick_attributes(kwd, tick_classes): # GH#18226 From 51ec9ed64ac6777cb4a63c95df25bbeb24391d3e Mon Sep 17 00:00:00 2001 From: Brock Mendel Date: Wed, 31 Jan 2018 18:59:12 -0800 Subject: [PATCH 2/4] add params to docstring --- pandas/tseries/offsets.py | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/pandas/tseries/offsets.py b/pandas/tseries/offsets.py index ec206e0997d0b..d8a5cae8cc17e 100644 --- a/pandas/tseries/offsets.py +++ b/pandas/tseries/offsets.py @@ -182,6 +182,29 @@ def __add__(date): date + BDay(0) == BDay.rollforward(date) Since 0 is a bit weird, we suggest avoiding its use. + + Parameters + ---------- + n : int (default 1) + normalize : bool (default False) + years : int or None + months : int or None + weeks : int or None + days : int or None + hours : int or None + minutes : int or None + seconds : int or None + microseconds : int or None + nanoseconds : int or None + year : int or None + month : int or None + day : int or None + weekday : int or None + hour : int or None + minute : int or None + second : int or None + microsecond : int or None + nanosecond : int or None """ _use_relativedelta = False _adjust_dst = False From aeb3e87ca24bd1c2ffe5919ca2aa561629f7dfde Mon Sep 17 00:00:00 2001 From: Brock Mendel Date: Mon, 5 Feb 2018 11:20:11 -0800 Subject: [PATCH 3/4] docstring, whatsnew note --- doc/source/whatsnew/v0.23.0.txt | 2 +- pandas/tseries/offsets.py | 20 ++++++++++++++++++++ 2 files changed, 21 insertions(+), 1 deletion(-) diff --git a/doc/source/whatsnew/v0.23.0.txt b/doc/source/whatsnew/v0.23.0.txt index b3905824f7e44..6c65b5509ae93 100644 --- a/doc/source/whatsnew/v0.23.0.txt +++ b/doc/source/whatsnew/v0.23.0.txt @@ -529,7 +529,7 @@ Offsets - Bug in :class:`FY5253Quarter`, :class:`LastWeekOfMonth` where rollback and rollforward behavior was inconsistent with addition and subtraction behavior (:issue:`18854`) - Bug in :class:`FY5253` where ``datetime`` addition and subtraction incremented incorrectly for dates on the year-end but not normalized to midnight (:issue:`18854`) - Bug in :class:`FY5253` where date offsets could incorrectly raise an ``AssertionError`` in arithmetic operatons (:issue:`14774`) - +- Bug in :class:`DateOffset` where keyword arguments ``week`` and ``milliseconds`` were accepted and ignored. Passing these will now raise ``ValueError`` (:issue:`19398`) Numeric ^^^^^^^ diff --git a/pandas/tseries/offsets.py b/pandas/tseries/offsets.py index 89f6ff65d2ad7..970dc56703823 100644 --- a/pandas/tseries/offsets.py +++ b/pandas/tseries/offsets.py @@ -187,6 +187,9 @@ def __add__(date): ---------- n : int (default 1) normalize : bool (default False) + + Parameters that ADD to the offset (like Timedelta) + -------------------------------------------------- years : int or None months : int or None weeks : int or None @@ -196,6 +199,9 @@ def __add__(date): seconds : int or None microseconds : int or None nanoseconds : int or None + + Parameters that REPLACE the offset value + ---------------------------------------- year : int or None month : int or None day : int or None @@ -205,6 +211,20 @@ def __add__(date): second : int or None microsecond : int or None nanosecond : int or None + + Examples + -------- + >>> ts = pd.Timestamp('2017-01-01 09:10:11') + >>> ts + DateOffset(months=3) + Timestamp('2017-04-01 09:10:11') + + >>> ts = pd.Timestamp('2017-01-01 09:10:11') + >>> ts + DateOffset(month=3) + Timestamp('2017-03-01 09:10:11') + + See Also + -------- + dateutil.relativedelta.relativedelta """ _use_relativedelta = False _adjust_dst = False From 8e947fe428c42b0c6204b7ee511a4c3fc5df6375 Mon Sep 17 00:00:00 2001 From: Brock Mendel Date: Thu, 19 Jul 2018 15:31:11 -0700 Subject: [PATCH 4/4] implement @datapythonistas docstring suggestion --- pandas/tseries/offsets.py | 65 +++++++++++++++++++++------------------ 1 file changed, 35 insertions(+), 30 deletions(-) diff --git a/pandas/tseries/offsets.py b/pandas/tseries/offsets.py index c27a13ec01322..dd4356aac1cd5 100644 --- a/pandas/tseries/offsets.py +++ b/pandas/tseries/offsets.py @@ -161,32 +161,41 @@ def __add__(date): Parameters ---------- - n : int (default 1) - normalize : bool (default False) - - Parameters that ADD to the offset (like Timedelta) - -------------------------------------------------- - years : int or None - months : int or None - weeks : int or None - days : int or None - hours : int or None - minutes : int or None - seconds : int or None - microseconds : int or None - nanoseconds : int or None - - Parameters that REPLACE the offset value - ---------------------------------------- - year : int or None - month : int or None - day : int or None - weekday : int or None - hour : int or None - minute : int or None - second : int or None - microsecond : int or None - nanosecond : int or None + n : int, default 1 + The number of time periods the offset represents. + normalize : bool, default False + Whether to round the result of a DateOffset addition down to the + previous midnight. + **kwds + Temporal parameter that add to or replace the offset value. + + Parameters that **add** to the offset (like Timedelta): + + - years + - months + - weeks + - days + - hours + - minutes + - seconds + - microseconds + - nanoseconds + + Parameters that **replace** the offset value: + + - year + - month + - day + - weekday + - hour + - minute + - second + - microsecond + - nanosecond + + See Also + -------- + dateutil.relativedelta.relativedelta Examples -------- @@ -197,10 +206,6 @@ def __add__(date): >>> ts = pd.Timestamp('2017-01-01 09:10:11') >>> ts + DateOffset(month=3) Timestamp('2017-03-01 09:10:11') - - See Also - -------- - dateutil.relativedelta.relativedelta """ _params = cache_readonly(BaseOffset._params.fget) _use_relativedelta = False