Fix invalid relativedelta_kwds #19398

jbrockmendel · 2018-01-25T19:16:02Z

closes #xxxx
tests added / passed
passes git diff upstream/master -u -- "*.py" | flake8 --diff
whatsnew entry

jreback · 2018-01-26T12:00:35Z

add a whatsnew entry. let's add/update a doc-string for DateOffset.

jbrockmendel · 2018-01-26T18:02:01Z

add a whatsnew entry

Saying what? This shouldn't change anything user-facing.

let's add/update a doc-string for DateOffset

Sure. Just in DateOffset.__doc__ listing valid kwargs?

…_kwds

codecov · 2018-01-27T00:48:45Z

Codecov Report

Merging #19398 into master will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##           master   #19398   +/-   ##
=======================================
  Coverage    91.6%    91.6%           
=======================================
  Files         150      150           
  Lines       48750    48750           
=======================================
  Hits        44657    44657           
  Misses       4093     4093

Flag	Coverage Δ
#multiple	`89.97% <ø> (ø)`	⬆️
#single	`41.75% <ø> (ø)`	⬆️

Impacted Files	Coverage Δ
pandas/tseries/offsets.py	`97% <ø> (ø)`	⬆️

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update ed10bf6...fe882f1. Read the comment docs.

jbrockmendel · 2018-02-01T03:00:17Z

Just added relativedelta params to the DateOffset docstring... not wild about encouraging users to use these.

jreback · 2018-02-01T12:59:02Z

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


correct, can you separate this into 2 subsections and make clear the different behavior (via an example)

In [1]: t = pd.Timestamp('20170101 09:10:11') # operate with the value In [3]: t + DateOffset(years=2018) Out[3]: datetime.datetime(4035, 1, 1, 9, 10, 11) In [5]: t + DateOffset(seconds=1) Out[5]: Timestamp('2017-01-01 09:10:12') # set the value In [6]: t + DateOffset(second=1) Out[6]: Timestamp('2017-01-01 09:10:01') In [8]: t + DateOffset(month=1) Out[8]: Timestamp('2017-01-01 09:10:11')

there is an issue to revisit this (IOW we should have 2 different offsets for this different behaviors)

Sure. The docstring is already pretty big and likely to get much bigger. Is there somewhere else part of it should go?

there is an issue to revisit this (IOW we should have 2 different offsets for this different behaviors)

Yah, IIRC there was a suggestion to have __new__ dispatch some special cases to Tick, MonthOffset, etc. I'm planning to take a swing at that after the immutabilization since __new__ and cython are tricky.

don't make it long, make it wide instead (its a bit non-standard ok)

n : int, default 1 normalize : bool, default False Parameters that ADD to the offset ---------------------------------- years, months, .... Parameters that REPLACE the offset value ----------- year, month

jreback · 2018-02-01T13:01:24Z

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',


technically this is an api change, IOW week & milliseconds cannot be passed anymore (maybe add this PR number somwhere)

Shoot you're right.

…_kwds

jreback · 2018-02-02T11:34:57Z

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


don't make it long, make it wide instead (its a bit non-standard ok)

n : int, default 1 normalize : bool, default False Parameters that ADD to the offset ---------------------------------- years, months, .... Parameters that REPLACE the offset value ----------- year, month

…_kwds

jreback · 2018-02-06T01:20:11Z

pandas/tseries/offsets.py

+    n : int (default 1)
+    normalize : bool (default False)
+
+    Parameters that ADD to the offset (like Timedelta)


@TomAugspurger @jorisvandenbossche

will this work formatting wise? (prob needs even more in this doc-string, but this is a good start)

It will not work formatting wise for sphinx / online docs, I think (should try out to be sure, but I think numpydoc does not accept custom sections)

Alternative would be to do like (but then with all options listed where I put ...):

Parameters ---------- ... years, months, weeks, ... nanoseconds : int, optional Parameters that ADD to the offset (like Timedelta) year, month, week, ..., nanosecond : int, optional Parameters that REPLACE the offset value

I think that recent numpydocs raise if there are extra sections, so this won't work.

…_kwds

jbrockmendel · 2018-02-10T01:43:00Z

There is another subtle problem here in that if relativedelta kwargs are passed and nano kwargs are passed, the nano is silently ignored (except in __repr__). I'll edit to raise instead of silently being incorrect.

@jorisvandenbossche 's formatting idea makes sense.

jbrockmendel · 2018-02-14T20:28:51Z

Temporarily closing to clear out the queue

jbrockmendel · 2018-07-10T21:12:12Z

@datapythonista thoughts on how to handle the doc string here?

datapythonista · 2018-07-11T04:21:06Z

What do you think about something like this?

class DateOffset(BaseOffset):
    """
    Standard kind of date increment used for a date range.

    Works exactly like relativedelta in terms of the keyword args you
    pass in, use of the keyword n is discouraged-- you would be better
    off specifying n in the keywords you use, but regardless it is
    there for you. n is needed for DateOffset subclasses.

    DateOffets work as follows.  Each offset specify a set of dates
    that conform to the DateOffset.  For example, Bday defines this
    set to be the set of dates that are weekdays (M-F).  To test if a
    date is in the set of a DateOffset dateOffset we can use the
    onOffset method: dateOffset.onOffset(date).

    If a date is not on a valid date, the rollback and rollforward
    methods can be used to roll the date to the nearest valid date
    before/after the date.

    DateOffsets can be created to move dates forward a given number of
    valid dates.  For example, Bday(2) can be added to a date to move
    it two business days forward.  If the date does not start on a
    valid date, first it is moved to a valid date.  Thus pseudo code
    is:

    def __add__(date):
      date = rollback(date) # does nothing if date is valid
      return date + <n number of periods>

    When a date offset is created for a negative number of periods,
    the date is first rolled forward.  The pseudo code is:

    def __add__(date):
      date = rollforward(date) # does nothing is date is valid
      return date + <n number of periods>

    Zero presents a problem.  Should it roll forward or back?  We
    arbitrarily have it rollforward:

    date + BDay(0) == BDay.rollforward(date)

    Since 0 is a bit weird, we suggest avoiding its use.

    Parameters
    ----------
    n : int, default 1
        ADD SHORT DESCRIPTION HERE
    normalize : bool, default False
        ADD SHORT DESCRIPTION HERE
    **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
    --------
    >>> 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')
    """

…_kwds

jbrockmendel · 2018-07-19T22:31:37Z

Implemented @datapythonista's suggestion, reopening.

jreback · 2018-07-20T13:29:50Z

thanks @jbrockmendel and @datapythonista

I think the doc-string is pretty good. maybe add some more examples?

Fix invalid relativedelta_kwds

bd7f8cf

jreback added the Frequency DateOffsets label Jan 26, 2018

Merge branch 'master' of https://github.com/pandas-dev/pandas into rd…

2010dbb

…_kwds

add params to docstring

51ec9ed

jreback requested changes Feb 1, 2018

View reviewed changes

jreback added the Docs label Feb 1, 2018

jreback reviewed Feb 1, 2018

View reviewed changes

Merge branch 'master' of https://github.com/pandas-dev/pandas into rd…

7a57cab

…_kwds

jreback requested changes Feb 2, 2018

View reviewed changes

jbrockmendel added 2 commits February 5, 2018 11:12

Merge branch 'master' of https://github.com/pandas-dev/pandas into rd…

2f2df38

…_kwds

docstring, whatsnew note

aeb3e87

jreback reviewed Feb 6, 2018

View reviewed changes

Merge branch 'master' of https://github.com/pandas-dev/pandas into rd…

fe882f1

…_kwds

jbrockmendel closed this Feb 14, 2018

jbrockmendel added 2 commits July 19, 2018 15:25

Merge branch 'master' of https://github.com/pandas-dev/pandas into rd…

06efb41

…_kwds

implement @datapythonistas docstring suggestion

8e947fe

jbrockmendel reopened this Jul 19, 2018

jreback added this to the 0.24.0 milestone Jul 20, 2018

jreback approved these changes Jul 20, 2018

View reviewed changes

jreback merged commit 1f6ddc4 into pandas-dev:master Jul 20, 2018

Sup3rGeo pushed a commit to Sup3rGeo/pandas that referenced this pull request Oct 1, 2018

Fix invalid relativedelta_kwds (pandas-dev#19398)

f3ed997

jbrockmendel deleted the rd_kwds branch April 5, 2020 17:40

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Fix invalid relativedelta_kwds #19398

Fix invalid relativedelta_kwds #19398

jbrockmendel commented Jan 25, 2018 •

edited

Loading

jreback commented Jan 26, 2018

jbrockmendel commented Jan 26, 2018 •

edited

Loading

codecov bot commented Jan 27, 2018 •

edited

Loading

jbrockmendel commented Feb 1, 2018

jreback Feb 1, 2018

jreback Feb 1, 2018

jbrockmendel Feb 1, 2018

jreback Feb 2, 2018

jreback Feb 1, 2018

jbrockmendel Feb 1, 2018

jreback Feb 2, 2018

jreback Feb 6, 2018

jorisvandenbossche Feb 6, 2018

jorisvandenbossche Feb 6, 2018

TomAugspurger Feb 6, 2018

jbrockmendel commented Feb 10, 2018

jbrockmendel commented Feb 14, 2018

jbrockmendel commented Jul 10, 2018

datapythonista commented Jul 11, 2018

jbrockmendel commented Jul 19, 2018

jreback commented Jul 20, 2018

Fix invalid relativedelta_kwds #19398

Fix invalid relativedelta_kwds #19398

Conversation

jbrockmendel commented Jan 25, 2018 • edited Loading

jreback commented Jan 26, 2018

jbrockmendel commented Jan 26, 2018 • edited Loading

codecov bot commented Jan 27, 2018 • edited Loading

Codecov Report

jbrockmendel commented Feb 1, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jbrockmendel commented Feb 10, 2018

jbrockmendel commented Feb 14, 2018

jbrockmendel commented Jul 10, 2018

datapythonista commented Jul 11, 2018

jbrockmendel commented Jul 19, 2018

jreback commented Jul 20, 2018

jbrockmendel commented Jan 25, 2018 •

edited

Loading

jbrockmendel commented Jan 26, 2018 •

edited

Loading

codecov bot commented Jan 27, 2018 •

edited

Loading