MRG: Merge branch 'steveha/datetime64_doc'

3 files changed, 179 insertions, 139 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
     --------
diff --git a/numpy/core/src/multiarray/datetime_busdaycal.c b/numpy/core/src/multiarray/datetime_busdaycal.c
index ae35212ea..018912ee8 100644
--- a/numpy/core/src/multiarray/datetime_busdaycal.c
+++ b/numpy/core/src/multiarray/datetime_busdaycal.c
@@ -46,6 +46,7 @@ PyArray_WeekMaskConverter(PyObject *weekmask_in, npy_bool *weekmask)
     if (PyBytes_Check(obj)) {
         char *str;
         Py_ssize_t len;
+        int i;
 
         if (PyBytes_AsStringAndSize(obj, &str, &len) < 0) {
             Py_DECREF(obj);
@@ -54,7 +55,6 @@ PyArray_WeekMaskConverter(PyObject *weekmask_in, npy_bool *weekmask)
 
         /* Length 7 is a string like "1111100" */
         if (len == 7) {
-            int i;
             for (i = 0; i < 7; ++i) {
                 switch(str[i]) {
                     case '0':
@@ -64,70 +64,81 @@ PyArray_WeekMaskConverter(PyObject *weekmask_in, npy_bool *weekmask)
                         weekmask[i] = 1;
                         break;
                     default:
-                        goto invalid_weekmask_string;
+                        goto general_weekmask_string;
                 }
             }
 
             goto finish;
         }
-        /* Length divisible by 3 is a string like "Mon" or "MonWedFri" */
-        else if (len % 3 == 0) {
-            int i;
-            memset(weekmask, 0, 7);
-            for (i = 0; i < len; i += 3) {
-                switch (str[i]) {
-                    case 'M':
-                        if (str[i+1] == 'o' && str[i+2] == 'n') {
-                            weekmask[0] = 1;
-                        }
-                        else {
-                            goto invalid_weekmask_string;
-                        }
-                        break;
-                    case 'T':
-                        if (str[i+1] == 'u' && str[i+2] == 'e') {
-                            weekmask[1] = 1;
-                        }
-                        else if (str[i+1] == 'h' && str[i+2] == 'u') {
-                            weekmask[3] = 1;
-                        }
-                        else {
-                            goto invalid_weekmask_string;
-                        }
-                        break;
-                    case 'W':
-                        if (str[i+1] == 'e' && str[i+2] == 'd') {
-                            weekmask[2] = 1;
-                        }
-                        else {
-                            goto invalid_weekmask_string;
-                        }
-                        break;
-                    case 'F':
-                        if (str[i+1] == 'r' && str[i+2] == 'i') {
-                            weekmask[4] = 1;
-                        }
-                        else {
-                            goto invalid_weekmask_string;
-                        }
-                        break;
-                    case 'S':
-                        if (str[i+1] == 'a' && str[i+2] == 't') {
-                            weekmask[5] = 1;
-                        }
-                        else if (str[i+1] == 'u' && str[i+2] == 'n') {
-                            weekmask[6] = 1;
-                        }
-                        else {
-                            goto invalid_weekmask_string;
-                        }
-                        break;
-                }
+
+general_weekmask_string:
+        /* a string like "SatSun" or "Mon Tue Wed" */
+        memset(weekmask, 0, 7);
+        for (i = 0; i < len; i += 3) {
+            while (isspace(str[i]))
+                ++i;
+
+            if (i == len) {
+                goto finish;
+            }
+            else if (i + 2 >= len) {
+                goto invalid_weekmask_string;
             }
 
-            goto finish;
+            switch (str[i]) {
+                case 'M':
+                    if (str[i+1] == 'o' && str[i+2] == 'n') {
+                        weekmask[0] = 1;
+                    }
+                    else {
+                        goto invalid_weekmask_string;
+                    }
+                    break;
+                case 'T':
+                    if (str[i+1] == 'u' && str[i+2] == 'e') {
+                        weekmask[1] = 1;
+                    }
+                    else if (str[i+1] == 'h' && str[i+2] == 'u') {
+                        weekmask[3] = 1;
+                    }
+                    else {
+                        goto invalid_weekmask_string;
+                    }
+                    break;
+                case 'W':
+                    if (str[i+1] == 'e' && str[i+2] == 'd') {
+                        weekmask[2] = 1;
+                    }
+                    else {
+                        goto invalid_weekmask_string;
+                    }
+                    break;
+                case 'F':
+                    if (str[i+1] == 'r' && str[i+2] == 'i') {
+                        weekmask[4] = 1;
+                    }
+                    else {
+                        goto invalid_weekmask_string;
+                    }
+                    break;
+                case 'S':
+                    if (str[i+1] == 'a' && str[i+2] == 't') {
+                        weekmask[5] = 1;
+                    }
+                    else if (str[i+1] == 'u' && str[i+2] == 'n') {
+                        weekmask[6] = 1;
+                    }
+                    else {
+                        goto invalid_weekmask_string;
+                    }
+                    break;
+                default:
+                    goto invalid_weekmask_string;
+            }
         }
 
+        goto finish;
+
 invalid_weekmask_string:
         PyErr_Format(PyExc_ValueError,
                 "Invalid business day weekmask string \"%s\"",
diff --git a/numpy/core/tests/test_datetime.py b/numpy/core/tests/test_datetime.py
index 2770364f0..563f9e87c 100644
--- a/numpy/core/tests/test_datetime.py
+++ b/numpy/core/tests/test_datetime.py
@@ -1440,8 +1440,28 @@ class TestDateTime(TestCase):
         # Default M-F weekmask
         assert_equal(bdd.weekmask, np.array([1,1,1,1,1,0,0], dtype='?'))
 
+        # Check string weekmask with varying whitespace.
+        bdd = np.busdaycalendar(weekmask="Sun TueWed  Thu\tFri")
+        assert_equal(bdd.weekmask, np.array([0,1,1,1,1,0,1], dtype='?'))
+
+        # Check length 7 0/1 string
+        bdd = np.busdaycalendar(weekmask="0011001")
+        assert_equal(bdd.weekmask, np.array([0,0,1,1,0,0,1], dtype='?'))
+
+        # Check length 7 string weekmask.
+        bdd = np.busdaycalendar(weekmask="Mon Tue")
+        assert_equal(bdd.weekmask, np.array([1,1,0,0,0,0,0], dtype='?'))
+
         # All-zeros weekmask should raise
         assert_raises(ValueError, np.busdaycalendar, weekmask=[0,0,0,0,0,0,0])
+        # weekday names must be correct case
+        assert_raises(ValueError, np.busdaycalendar, weekmask="satsun")
+        # All-zeros weekmask should raise
+        assert_raises(ValueError, np.busdaycalendar, weekmask="")
+        # Invalid weekday name codes should raise
+        assert_raises(ValueError, np.busdaycalendar, weekmask="Mon Tue We")
+        assert_raises(ValueError, np.busdaycalendar, weekmask="Max")
+        assert_raises(ValueError, np.busdaycalendar, weekmask="Monday Tue")
 
     def test_datetime_busday_holidays_offset(self):
         # With exactly one holiday