Initial implementation of holiday and holiday calendar.

doc/source/timeseries.rst

@@ -546,6 +546,17 @@ calendars which account for local holidays and local weekend conventions.
     print(dts)
     print(Series(dts.weekday, dts).map(Series('Mon Tue Wed Thu Fri Sat Sun'.split())))
 
+As of v0.14 holiday calendars can be used to provide the list of holidays.  See the
+:ref:`holiday calendar<timeseries.holiday>` section for more information.
+
+.. ipython:: python
+
+    from pandas.tseries.holiday import USFederalHolidayCalendar
+    bday_us = CustomBusinessDay(calendar=USFederalHolidayCalendar())
+    dt = datetime(2014, 1, 17) #Friday before MLK Day
+    print(dt + bday_us) #Tuesday after MLK Day
+
+
 .. note::
 
     The frequency string 'C' is used to indicate that a CustomBusinessDay
@@ -712,6 +723,65 @@ and business year ends. Please also note the legacy time rule for milliseconds
 ``ms`` versus the new offset alias for month start ``MS``. This means that
 offset alias parsing is case sensitive.
 
+.. _timeseries.holiday:
+
+Holidays / Holiday Calendars
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Holidays and calendars provide a simple way to define holiday rules to be used
+with ``CustomBusinessDay`` or in other analysis that requires a predefined
+set of holidays.  The ``AbstractHolidayCalendar`` class provides all the necessary 
+methods to return a list of holidays and only ``rules`` need to be defined
+in a specific holiday calendar class.  ``USFederalHolidayCalendar`` is the only
+calendar that exists and primarily serves as an example for developing
+other holiday calendars.
+
+For holidays that occur on fixed dates (e.g., US Memorial Day or July 4th) an 
+observance rule determines when that holiday is observed if it falls on a weekend
+or some other non-observed day.  Defined observance rules are:
+
+.. csv-table::
+    :header: "Rule", "Description"
+    :widths: 15, 70
+
+    "nearest_workday", "move Saturday to Friday and Sunday to Monday"
+    "sunday_to_monday", "move Sunday to following Monday"
+    "next_monday_or_tuesday", "move Saturday to Monday and Sunday/Monday to Tuesday"
+    "previous_friday", move Saturday and Sunday to previous Friday"
+    "next_monday", "move Saturday and Sunday to following Monday"
+
+An example of how holidays and holiday calendars are defined:
+
+.. ipython:: python
+
+    from pandas.tseries.holiday import Holiday, USMemorialDay,\
+        AbstractHolidayCalendar, nearest_workday, MO
+    class ExampleCalendar(AbstractHolidayCalendar):
+        rules = [
+            USMemorialDay,
+            Holiday('July 4th', month=7, day=4, observance=nearest_workday),
+            Holiday('Columbus Day', month=10, day=1, 
+                offset=DateOffset(weekday=MO(2))), #same as 2*Week(weekday=2)
+            ]
+    cal = ExampleCalendar()
+    cal.holidays(datetime(2012, 1, 1), datetime(2012, 12, 31)) #holiday list
+    datetime(2012, 5, 25) + CustomBusinessDay(calendar=cal)
+
+Every calendar class is accessible by name using the ``get_calendar`` function
+which returns a holiday class instance.  Any imported calendar class will
+automatically be available by this function.  Also, ``HolidayCalendarFactory``
+provides an easy interface to create calendars that are combinations of calendars
+or calendars with additional rules.
+
+.. ipython:: python
+
+    from pandas.tseries.holiday import get_calendar, HolidayCalendarFactory,\
+        USLaborDay
+    cal = get_calendar('ExampleCalendar')
+    cal.rules
+    new_cal = HolidayCalendarFactory('NewExampleCalendar', cal, USLaborDay)
+    new_cal.rules
+
 .. _timeseries.advanced_datetime:
 
 Time series-related instance methods

doc/source/v0.14.0.txt

@@ -308,7 +308,7 @@ Asymmetrical error bars are also supported, however raw error values must be pro
 Prior Version Deprecations/Changes
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Therse are prior version deprecations that are taking effect as of 0.14.0.
+There are prior version deprecations that are taking effect as of 0.14.0.
 
 - Remove ``column`` keyword from ``DataFrame.sort`` (:issue:`4370`)
 
@@ -376,6 +376,7 @@ Enhancements
   file. (:issue:`6545`)
 - ``pandas.io.gbq`` now handles reading unicode strings properly. (:issue:`5940`)
 - Improve performance of ``CustomBusinessDay`` (:issue:`6584`)
+- :ref:`Holidays and holiday calendars<timeseries.holiday>` are now available and can be used with CustomBusinessDay.
 
 Performance
 ~~~~~~~~~~~