MRG: Merge branch 'steveha/datetime64_doc'

1 files changed, 92 insertions, 83 deletions

diff --git a/numpy/add_newdocs.py b/numpy/add_newdocs.py
index 1e1d237a4..64f2f436a 100644
--- a/numpy/add_newdocs.py
+++ b/numpy/add_newdocs.py
@@ -5993,44 +5993,52 @@ add_newdoc('numpy.core.multiarray', 'busdaycalendar',
     """
     busdaycalendar(weekmask='1111100', holidays=None)
 
-    A business day calendar object that efficiently stores
-    information defining business days for the business
-    day-related functions.
+    A business day calendar object that efficiently stores information
+    defining valid days for the busday family of functions.
+
+    The default valid days are Monday through Friday ("business days").
+    A busdaycalendar object can be specified with any set of weekly
+    valid days, plus an optional "holiday" dates that always will be invalid.
+
+    Once a busdaycalendar object is created, the weekmask and holidays
+    cannot be modified.
 
     .. versionadded:: 1.7.0
 
     Parameters
     ----------
     weekmask : str or array_like of bool, optional
-        A seven-element array indicating which of Monday through Sunday may
-        be valid business days. May be specified as a list or array, like
-        [1,1,1,1,1,0,0], a length-seven string like '1111100', or a string
-        of three-letter weekday names, like 'MonTueWedThuFri'. The latter
-        string representation is most useful when only one day of the
-        week is important, like 'Mon' if you want to calculate the date
-        of Easter.
+        A seven-element array indicating which of Monday through Sunday are
+        valid days. May be specified as a length-seven list or array, like
+        [1,1,1,1,1,0,0]; a length-seven string, like '1111100'; or a string
+        like "Mon Tue Wed Thu Fri", made up of 3-character abbreviations for
+        weekdays, optionally separated by white space. Valid abbreviations
+        are: Mon Tue Wed Thu Fri Sat Sun
     holidays : array_like of datetime64[D], optional
-        An array of dates which should be blacked out from being considered
-        as business days. They may be specified in any order, and NaT
-        (not-a-time) dates are ignored. Internally, this list is normalized
-        into a form suited for fast business day calculations.
+        An array of dates to consider as invalid dates, no matter which
+        weekday they fall upon.  Holiday dates may be specified in any
+        order, and NaT (not-a-time) dates are ignored.  This list is
+        saved in a normalized form that is suited for fast calculations
+        of valid days.
 
     Returns
     -------
     out : busdaycalendar
         A business day calendar object containing the specified
-        weekmask and holidays.
+        weekmask and holidays values.
 
     See Also
     --------
-    is_busday : Returns a boolean array indicating valid business days.
-    busday_offset : Applies an offset counted in business days.
-    busday_count : Counts how many business days are in a half-open date range.
+    is_busday : Returns a boolean array indicating valid days.
+    busday_offset : Applies an offset counted in valid days.
+    busday_count : Counts how many valid days are in a half-open date range.
 
     Attributes
     ----------
-    weekmask : seven-element array of bool
-    holidays : sorted array of datetime64[D]
+    Note: once a busdaycalendar object is created, you cannot modify the
+    weekmask or holidays.  The attributes return copies of internal data.
+    weekmask : (copy) seven-element array of bool
+    holidays : (copy) sorted array of datetime64[D]
 
     Examples
     --------
@@ -6046,17 +6054,16 @@ add_newdoc('numpy.core.multiarray', 'busdaycalendar',
     """)
 
 add_newdoc('numpy.core.multiarray', 'busdaycalendar', ('weekmask',
-    """A copy of the seven-element boolean mask indicating valid business days."""))
+    """A copy of the seven-element boolean mask indicating valid days."""))
 
 add_newdoc('numpy.core.multiarray', 'busdaycalendar', ('holidays',
-    """A copy of the holiday array indicating blacked out business days."""))
+    """A copy of the holiday array indicating additional invalid days."""))
 
 add_newdoc('numpy.core.multiarray', 'is_busday',
     """
     is_busday(dates, weekmask='1111100', holidays=None, busdaycal=None, out=None)
 
-    Calculates which of the given dates are valid business days, and
-    which are not.
+    Calculates which of the given dates are valid days, and which are not.
 
     .. versionadded:: 1.7.0
 
@@ -6065,20 +6072,19 @@ add_newdoc('numpy.core.multiarray', 'is_busday',
     dates : array_like of datetime64[D]
         The array of dates to process.
     weekmask : str or array_like of bool, optional
-        A seven-element array indicating which of Monday through Sunday may
-        be valid business days. May be specified as a list or array, like
-        [1,1,1,1,1,0,0], a length-seven string like '1111100', or a string
-        of three-letter weekday names, like 'MonTueWedThuFri'. The latter
-        string representation is most useful when only one day of the
-        week is important, like 'Mon' if you want to calculate the date
-        of Easter.
+        A seven-element array indicating which of Monday through Sunday are
+        valid days. May be specified as a length-seven list or array, like
+        [1,1,1,1,1,0,0]; a length-seven string, like '1111100'; or a string
+        like "Mon Tue Wed Thu Fri", made up of 3-character abbreviations for
+        weekdays, optionally separated by white space. Valid abbreviations
+        are: Mon Tue Wed Thu Fri Sat Sun
     holidays : array_like of datetime64[D], optional
-        An array of dates which should be blacked out from being considered
-        as business days. They may be specified in any order, and NaT
-        (not-a-time) dates are ignored. Internally, this list is normalized
-        into a form suited for fast business day calculations.
+        An array of dates to consider as invalid dates.  They may be
+        specified in any order, and NaT (not-a-time) dates are ignored.
+        This list is saved in a normalized form that is suited for
+        fast calculations of valid days.
     busdaycal : busdaycalendar, optional
-        A `busdaycalendar` object which specifies the business days. If this
+        A `busdaycalendar` object which specifies the valid days. If this
         parameter is provided, neither weekmask nor holidays may be
         provided.
     out : array of bool, optional
@@ -6088,13 +6094,13 @@ add_newdoc('numpy.core.multiarray', 'is_busday',
     -------
     out : array of bool
         An array with the same shape as ``dates``, containing True for
-        each valid business day, and False for the others.
+        each valid day, and False for each invalid day.
 
     See Also
     --------
-    busdaycalendar: An object for efficiently specifying which are business days.
-    busday_offset : Applies an offset counted in business days.
-    busday_count : Counts how many business days are in a half-open date range.
+    busdaycalendar: An object that specifies a custom set of valid days.
+    busday_offset : Applies an offset counted in valid days.
+    busday_count : Counts how many valid days are in a half-open date range.
 
     Examples
     --------
@@ -6108,9 +6114,9 @@ add_newdoc('numpy.core.multiarray', 'busday_offset',
     """
     busday_offset(dates, offsets, roll='raise', weekmask='1111100', holidays=None, busdaycal=None, out=None)
 
-    First adjusts the date to fall on a business day according to
+    First adjusts the date to fall on a valid day according to
     the ``roll`` rule, then applies offsets to the given dates
-    counted in business days.
+    counted in valid days.
 
     .. versionadded:: 1.7.0
 
@@ -6121,36 +6127,35 @@ add_newdoc('numpy.core.multiarray', 'busday_offset',
     offsets : array_like of int
         The array of offsets, which is broadcast with ``dates``.
     roll : {'raise', 'nat', 'forward', 'following', 'backward', 'preceding', 'modifiedfollowing', 'modifiedpreceding'}, optional
-        How to treat dates that do not fall on a business day. The default
+        How to treat dates that do not fall on a valid day. The default
         is 'raise'.
 
-          * 'raise' means to raise an exception for invalid business days.
-          * 'nat' means to return a NaT (not-a-time) for invalid business days.
-          * 'forward' and 'following' mean to take the first business day
+          * 'raise' means to raise an exception for an invalid day.
+          * 'nat' means to return a NaT (not-a-time) for an invalid day.
+          * 'forward' and 'following' mean to take the first valid day
             later in time.
-          * 'backward' and 'preceding' mean to take the first business day
+          * 'backward' and 'preceding' mean to take the first valid day
             earlier in time.
-          * 'modifiedfollowing' means to take the first business day
+          * 'modifiedfollowing' means to take the first valid day
             later in time unless it is across a Month boundary, in which
-            case to take the first business day earlier in time.
-          * 'modifiedpreceding' means to take the first business day
+            case to take the first valid day earlier in time.
+          * 'modifiedpreceding' means to take the first valid day
             earlier in time unless it is across a Month boundary, in which
-            case to take the first business day later in time.
+            case to take the first valid day later in time.
     weekmask : str or array_like of bool, optional
-        A seven-element array indicating which of Monday through Sunday may
-        be valid business days. May be specified as a list or array, like
-        [1,1,1,1,1,0,0], a length-seven string like '1111100', or a string
-        of three-letter weekday names, like 'MonTueWedThuFri'. The latter
-        string representation is most useful when only one day of the
-        week is important, like 'Mon' if you want to calculate the date
-        of Easter.
+        A seven-element array indicating which of Monday through Sunday are
+        valid days. May be specified as a length-seven list or array, like
+        [1,1,1,1,1,0,0]; a length-seven string, like '1111100'; or a string
+        like "Mon Tue Wed Thu Fri", made up of 3-character abbreviations for
+        weekdays, optionally separated by white space. Valid abbreviations
+        are: Mon Tue Wed Thu Fri Sat Sun
     holidays : array_like of datetime64[D], optional
-        An array of dates which should be blacked out from being considered
-        as business days. They may be specified in any order, and NaT
-        (not-a-time) dates are ignored. Internally, this list is normalized
-        into a form suited for fast business day calculations.
+        An array of dates to consider as invalid dates.  They may be
+        specified in any order, and NaT (not-a-time) dates are ignored.
+        This list is saved in a normalized form that is suited for
+        fast calculations of valid days.
     busdaycal : busdaycalendar, optional
-        A `busdaycalendar` object which specifies the business days. If this
+        A `busdaycalendar` object which specifies the valid days. If this
         parameter is provided, neither weekmask nor holidays may be
         provided.
     out : array of datetime64[D], optional
@@ -6164,9 +6169,9 @@ add_newdoc('numpy.core.multiarray', 'busday_offset',
 
     See Also
     --------
-    busdaycalendar: An object for efficiently specifying which are business days.
-    is_busday : Returns a boolean array indicating valid business days.
-    busday_count : Counts how many business days are in a half-open date range.
+    busdaycalendar: An object that specifies a custom set of valid days.
+    is_busday : Returns a boolean array indicating valid days.
+    busday_count : Counts how many valid days are in a half-open date range.
 
     Examples
     --------
@@ -6199,9 +6204,14 @@ add_newdoc('numpy.core.multiarray', 'busday_count',
     """
     busday_count(begindates, enddates, weekmask='1111100', holidays=[], busdaycal=None, out=None)
 
-    Counts the number of business days between `begindates` and
+    Counts the number of valid days between `begindates` and
     `enddates`, not including the day of `enddates`.
 
+    If ``enddates`` specifies a date value that is earlier than the
+    corresponding ``begindates`` date value, the count will be 0.
+    However, in future this may change to a negative count of valid
+    days.
+
     .. versionadded:: 1.7.0
 
     Parameters
@@ -6212,20 +6222,19 @@ add_newdoc('numpy.core.multiarray', 'busday_count',
         The array of the end dates for counting, which are excluded
         from the count themselves.
     weekmask : str or array_like of bool, optional
-        A seven-element array indicating which of Monday through Sunday may
-        be valid business days. May be specified as a list or array, like
-        [1,1,1,1,1,0,0], a length-seven string like '1111100', or a string
-        of three-letter weekday names, like 'MonTueWedThuFri'. The latter
-        string representation is most useful when only one day of the
-        week is important, like 'Mon' if you want to calculate the date
-        of Easter.
+        A seven-element array indicating which of Monday through Sunday are
+        valid days. May be specified as a length-seven list or array, like
+        [1,1,1,1,1,0,0]; a length-seven string, like '1111100'; or a string
+        like "Mon Tue Wed Thu Fri", made up of 3-character abbreviations for
+        weekdays, optionally separated by white space. Valid abbreviations
+        are: Mon Tue Wed Thu Fri Sat Sun
     holidays : array_like of datetime64[D], optional
-        An array of dates which should be blacked out from being considered
-        as business days. They may be specified in any order, and NaT
-        (not-a-time) dates are ignored. Internally, this list is normalized
-        into a form suited for fast business day calculations.
+        An array of dates to consider as invalid dates.  They may be
+        specified in any order, and NaT (not-a-time) dates are ignored.
+        This list is saved in a normalized form that is suited for
+        fast calculations of valid days.
     busdaycal : busdaycalendar, optional
-        A `busdaycalendar` object which specifies the business days. If this
+        A `busdaycalendar` object which specifies the valid days. If this
         parameter is provided, neither weekmask nor holidays may be
         provided.
     out : array of int, optional
@@ -6235,14 +6244,14 @@ add_newdoc('numpy.core.multiarray', 'busday_count',
     -------
     out : array of int
         An array with a shape from broadcasting ``begindates`` and ``enddates``
-        together, containing the number of business days between
+        together, containing the number of valid days between
         the begin and end dates.
 
     See Also
     --------
-    busdaycalendar: An object for efficiently specifying which are business days.
-    is_busday : Returns a boolean array indicating valid business days.
-    busday_offset : Applies an offset counted in business days.
+    busdaycalendar: An object that specifies a custom set of valid days.
+    is_busday : Returns a boolean array indicating valid days.
+    busday_offset : Applies an offset counted in valid days.
 
     Examples
     --------