Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fix invalid relativedelta_kwds #19398

Merged
merged 9 commits into from Jul 20, 2018

Conversation

Projects
None yet
5 participants
@jbrockmendel
Copy link
Member

commented Jan 25, 2018

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

This comment has been minimized.

Copy link
Contributor

commented Jan 26, 2018

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

@jreback jreback added the Frequency label Jan 26, 2018

@jbrockmendel

This comment has been minimized.

Copy link
Member Author

commented Jan 26, 2018

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?

@codecov

This comment has been minimized.

Copy link

commented Jan 27, 2018

Codecov Report

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

Impacted file tree graph

@@           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

This comment has been minimized.

Copy link
Member Author

commented Feb 1, 2018

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

@@ -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

This comment has been minimized.

Copy link
@jreback

jreback Feb 1, 2018

Contributor

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

This comment has been minimized.

Copy link
@jreback

jreback Feb 1, 2018

Contributor

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

This comment has been minimized.

Copy link
@jbrockmendel

jbrockmendel Feb 1, 2018

Author Member

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.

This comment has been minimized.

Copy link
@jreback

jreback Feb 2, 2018

Contributor

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 jreback added the Docs label Feb 1, 2018

@@ -243,10 +243,10 @@ def _validate_business_time(t_input):

relativedelta_kwds = set([
'years', 'months', 'weeks', 'days',
'year', 'month', 'week', 'day', 'weekday',

This comment has been minimized.

Copy link
@jreback

jreback Feb 1, 2018

Contributor

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

This comment has been minimized.

Copy link
@jbrockmendel

jbrockmendel Feb 1, 2018

Author Member

Shoot you're right.

@@ -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

This comment has been minimized.

Copy link
@jreback

jreback Feb 2, 2018

Contributor

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

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

This comment has been minimized.

Copy link
@jreback

jreback Feb 6, 2018

Contributor

@TomAugspurger @jorisvandenbossche

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

This comment has been minimized.

Copy link
@jorisvandenbossche

jorisvandenbossche Feb 6, 2018

Member

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)

This comment has been minimized.

Copy link
@jorisvandenbossche

jorisvandenbossche Feb 6, 2018

Member

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

This comment has been minimized.

Copy link
@TomAugspurger

TomAugspurger Feb 6, 2018

Contributor

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

@jbrockmendel

This comment has been minimized.

Copy link
Member Author

commented Feb 10, 2018

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

This comment has been minimized.

Copy link
Member Author

commented Feb 14, 2018

Temporarily closing to clear out the queue

@jbrockmendel

This comment has been minimized.

Copy link
Member Author

commented Jul 10, 2018

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

@datapythonista

This comment has been minimized.

Copy link
Member

commented Jul 11, 2018

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')
    """

screenshot at 2018-07-10 23-17-58

@jbrockmendel jbrockmendel reopened this Jul 19, 2018

@jbrockmendel

This comment has been minimized.

Copy link
Member Author

commented Jul 19, 2018

Implemented @datapythonista's suggestion, reopening.

@jreback jreback added this to the 0.24.0 milestone Jul 20, 2018

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

3 checks passed

ci/circleci Your tests passed on CircleCI!
Details
continuous-integration/appveyor/pr AppVeyor build succeeded
Details
continuous-integration/travis-ci/pr The Travis CI build passed
Details
@jreback

This comment has been minimized.

Copy link
Contributor

commented Jul 20, 2018

thanks @jbrockmendel and @datapythonista

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

alimcmaster1 added a commit to alimcmaster1/pandas that referenced this pull request Aug 12, 2018

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.