AbstractHolidayCalendar: suggestion to update documentation with correct usage

[szeitlin]

    from pandas.tseries.holiday import Holiday, nearest_workday, get_calendar,    HolidayCalendarFactory, USPresidentsDay, \
USMemorialDay, USLaborDay, USThanksgivingDay, AbstractHolidayCalendar, USFederalHolidayCalendar

    from pandas.util.print_versions import show_versions
    >>> show_versions()

INSTALLED VERSIONS
------------------
commit: None
python: 3.4.3.final.0
python-bits: 64
OS: Linux
OS-release: 3.13.0-24-generic
machine: x86_64
processor: x86_64
byteorder: little
LC_ALL: en_US.UTF-8
LANG: en_US.UTF-8

pandas: 0.16.2
nose: 1.3.4
Cython: None
numpy: 1.9.1
scipy: None
statsmodels: None
IPython: 4.0.0
sphinx: None
patsy: None
dateutil: 2.2
pytz: 2013.9
bottleneck: None
tables: None
numexpr: None
matplotlib: 1.3.1
openpyxl: 2.1.4
xlrd: None
xlwt: None
xlsxwriter: None
lxml: 3.4.4
bs4: 4.3.1
html5lib: None
httplib2: None
apiclient: None
sqlalchemy: 0.9.7
pymysql: None
psycopg2: 2.4.6 (dt dec pq3 ext)

    >>> class MyCalendar(AbstractHolidayCalendar):
    rules = [
        Holiday("New Years Day", month=1, day=1, observance=nearest_workday),
        USPresidentsDay,
        USMemorialDay,
        Holiday("Independence Day", month=7, day=4, observance=nearest_workday),
        USLaborDay,
        Holiday("Veterans Day", month=11, day=11, observance=nearest_workday),
        USThanksgivingDay,
        Holiday("Christmas", month=12, day=25, observance=nearest_workday)
    ]

    >>> cal = MyCalendar()
    >>> cal.rules

[Holiday: New Years Day (month=1, day=1, observance=<function nearest_workday at 0x7f6dbbfd5bf8>),
 Holiday: Presidents Day (month=2, day=1, offset=<DateOffset: kwds={'weekday': MO(+3)}>),
 Holiday: MemorialDay (month=5, day=24, offset=<DateOffset: kwds={'weekday': MO(+1)}>),
 Holiday: Independence Day (month=7, day=4, observance=<function nearest_workday at 0x7f6dbbfd5bf8>),
 Holiday: Labor Day (month=9, day=1, offset=<DateOffset: kwds={'weekday': MO(+1)}>),
 Holiday: Veterans Day (month=11, day=11, observance=<function nearest_workday at 0x7f6dbbfd5bf8>),
 Holiday: Thanksgiving (month=11, day=1, offset=<DateOffset: kwds={'weekday': TH(+4)}>),
 Holiday: Christmas (month=12, day=25, observance=<function nearest_workday at 0x7f6dbbfd5bf8>)]

#this works as expected, but isn't in the documentation:

    >>> cal.holidays(start='11/5/2014', end='11/4/2015')

DatetimeIndex(['2014-11-11', '2014-11-27', '2014-12-25', '2015-01-01',
               '2015-02-16', '2015-05-25', '2015-07-03', '2015-09-07'],
              dtype='datetime64[ns]', freq=None, tz=None)

#this is what the documentation says to do, and the results make no sense:

    from pandas.tseries.offsets import CDay #docs don't actually say where CDay comes from, I had to dig that up myself

    >>> oneyear = pd.DatetimeIndex(start='11/5/2014', end='11/4/2015', freq=CDay(calendar=cal)).to_pydatetime()
    >>> oneyear

array([datetime.datetime(2014, 11, 5, 0, 0),
       datetime.datetime(2014, 11, 6, 0, 0),
       datetime.datetime(2014, 11, 7, 0, 0),
       datetime.datetime(2014, 11, 10, 0, 0),
       datetime.datetime(2014, 11, 11, 0, 0),
       datetime.datetime(2014, 11, 12, 0, 0),
       datetime.datetime(2014, 11, 13, 0, 0),
       datetime.datetime(2014, 11, 14, 0, 0),
       datetime.datetime(2014, 11, 17, 0, 0),
       datetime.datetime(2014, 11, 18, 0, 0),
       datetime.datetime(2014, 11, 19, 0, 0),
       datetime.datetime(2014, 11, 20, 0, 0),
       datetime.datetime(2014, 11, 21, 0, 0),
       datetime.datetime(2014, 11, 24, 0, 0),
       datetime.datetime(2014, 11, 25, 0, 0),
       datetime.datetime(2014, 11, 26, 0, 0),
       datetime.datetime(2014, 11, 27, 0, 0),
       datetime.datetime(2014, 11, 28, 0, 0), etc.

[rockg]

You are right, your last example does not make any sense. It should skip 11/11 (just like the documentation example skips 7/4). Seems like something is not working as expected.

As far as .holidays(startDate, endDate) I think we could add an example to the docs but this should probably go into the API documentation.

The CDay import is suppressed by the docs -- from pandas.tseries.offsets import *. I don't see any harm in making this explicit.

[rockg]

I do not see the same behavior as you not skipping 11/11 on pandas 0.17.0. Can you try and see if you see the same thing under 0.17.0?

oneyear = pd.DatetimeIndex(start='11/5/2014', end='11/4/2015', freq=CDay(calendar=cal)).to_pydatetime()
oneyear
Out[10]: 
array([datetime.datetime(2014, 11, 5, 0, 0),
       datetime.datetime(2014, 11, 6, 0, 0),
       datetime.datetime(2014, 11, 7, 0, 0),
       datetime.datetime(2014, 11, 10, 0, 0),
       datetime.datetime(2014, 11, 12, 0, 0),
       datetime.datetime(2014, 11, 13, 0, 0),
       datetime.datetime(2014, 11, 14, 0, 0),
       datetime.datetime(2014, 11, 17, 0, 0),
       datetime.datetime(2014, 11, 18, 0, 0),
       datetime.datetime(2014, 11, 19, 0, 0),
       datetime.datetime(2014, 11, 20, 0, 0),
       datetime.datetime(2014, 11, 21, 0, 0),
       datetime.datetime(2014, 11, 24, 0, 0),
       datetime.datetime(2014, 11, 25, 0, 0),
       datetime.datetime(2014, 11, 26, 0, 0),
       datetime.datetime(2014, 11, 28, 0, 0),

[szeitlin]

Skipping 11/11 was not the point I was making. I think it probably should skip that day (Veterans Day). I was saying I expected it to give me back only the dates from the calendar, and instead it gave me back what looks like every day except the dates from the calendar.

[rockg]

CDay is custom business day so it supposed to give business days skipping holidays/weekends.

"The CDay or CustomBusinessDay class provides a parametric BusinessDay class which can be used to create customized business day calendars which account for local holidays and local weekend conventions."

[szeitlin]

that's good. The docs need some better descriptions of when and how to actually use a calendar object. It's especially bad to introduce things like CDay that live elsewhere in the code without first defining them and/or linking to them.