DEPR: Deprecate cdate_range merge into bdate_range

Author: jschendel

doc/source/api.rst

@@ -218,7 +218,6 @@ Top-level dealing with datetimelike
    to_timedelta
    date_range
    bdate_range
-   cdate_range
    period_range
    timedelta_range
    infer_freq

doc/source/timeseries.rst

@@ -164,6 +164,7 @@ Other Enhancements
 - :func:`read_excel` raises ``ImportError`` with a better message if ``xlrd`` is not installed. (:issue:`17613`)
 - :func:`read_json` now accepts a ``chunksize`` parameter that can be used when ``lines=True``. If ``chunksize`` is passed, read_json now returns an iterator which reads in ``chunksize`` lines with each iteration. (:issue:`17048`)
 - :meth:`DataFrame.assign` will preserve the original order of ``**kwargs`` for Python 3.6+ users instead of sorting the column names
+- :func:`bdate_range` has gained ``weekmask`` and ``holidays`` parameters for constructing custom frequency date ranges (:issue:`17596`)
 
 
 .. _whatsnew_0210.api_breaking:
@@ -488,7 +489,7 @@ Additionally, DataFrames with datetime columns that were parsed by :func:`read_s
 Consistency of Range Functions
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-In previous versions, there were some inconsistencies between the various range functions: :func:`date_range`, :func:`bdate_range`, :func:`cdate_range`, :func:`period_range`, :func:`timedelta_range`, and :func:`interval_range`. (:issue:`17471`).
+In previous versions, there were some inconsistencies between the various range functions: :func:`date_range`, :func:`bdate_range`, :func:`period_range`, :func:`timedelta_range`, and :func:`interval_range`. (:issue:`17471`).
 
 One of the inconsistent behaviors occurred when the ``start``, ``end`` and ``period`` parameters were all specified, potentially leading to ambiguous ranges.  When all three parameters were passed, ``interval_range`` ignored the ``period`` parameter, ``period_range`` ignored the ``end`` parameter, and the other range functions raised.  To promote consistency among the range functions, and avoid potentially ambiguous ranges, ``interval_range`` and ``period_range`` will now raise when all three parameters are passed.
 
@@ -571,6 +572,7 @@ Deprecations
 - :func:`SeriesGroupBy.nth` has deprecated ``True`` in favor of ``'all'`` for its kwarg ``dropna`` (:issue:`11038`).
 - :func:`DataFrame.as_blocks` is deprecated, as this is exposing the internal implementation (:issue:`17302`)
 - ``pd.TimeGrouper`` is deprecated in favor of :class:`pandas.Grouper` (:issue:`16747`)
+- ``cdate_range`` has been deprecated in favor of :func:`bdate_range` (:issue:`17596`)
 
 .. _whatsnew_0210.deprecations.argmin_min
 

doc/source/whatsnew/v0.21.0.txt

@@ -16,8 +16,7 @@
                                PeriodIndex, NaT)
 from pandas.core.indexes.period import Period, period_range, pnow
 from pandas.core.indexes.timedeltas import Timedelta, timedelta_range
-from pandas.core.indexes.datetimes import (Timestamp, date_range, bdate_range,
-                                           cdate_range)
+from pandas.core.indexes.datetimes import Timestamp, date_range, bdate_range
 from pandas.core.indexes.interval import Interval, interval_range
 
 from pandas.core.series import Series

pandas/core/api.py

@@ -17,6 +17,7 @@
     is_period_dtype,
     is_bool_dtype,
     is_string_dtype,
+    is_string_like,
     is_list_like,
     is_scalar,
     pandas_dtype,
@@ -37,7 +38,8 @@
     Resolution)
 from pandas.core.indexes.datetimelike import (
     DatelikeOps, TimelikeOps, DatetimeIndexOpsMixin)
-from pandas.tseries.offsets import DateOffset, generate_range, Tick, CDay
+from pandas.tseries.offsets import (
+    DateOffset, generate_range, Tick, CDay, prefix_mapping)
 from pandas.core.tools.datetimes import (
     parse_time_string, normalize_date, to_time)
 from pandas.core.tools.timedeltas import to_timedelta
@@ -2049,7 +2051,8 @@ def date_range(start=None, end=None, periods=None, freq='D', tz=None,
 
 
 def bdate_range(start=None, end=None, periods=None, freq='B', tz=None,
-                normalize=True, name=None, closed=None, **kwargs):
+                normalize=True, name=None, weekmask='Mon Tue Wed Thu Fri',
+                holidays=None, closed=None, **kwargs):
     """
     Return a fixed frequency DatetimeIndex, with business day as the default
     frequency
@@ -2071,6 +2074,19 @@ def bdate_range(start=None, end=None, periods=None, freq='B', tz=None,
         Normalize start/end dates to midnight before generating date range
     name : string, default None
         Name of the resulting DatetimeIndex
+    weekmask : string, default 'Mon Tue Wed Thu Fri'
+        weekmask of valid business days, passed to ``numpy.busdaycalendar``,
+        only used when custom frequency strings are passed
+
+        .. versionadded:: 0.21.0
+
+    holidays : list-like or None, default None
+        list-like of dates to exclude from the set of valid business days,
+        passed to ``numpy.busdaycalendar``, only used when custom frequency
+        strings are passed
+
+        .. versionadded:: 0.21.0
+
     closed : string, default None
         Make the interval closed with respect to the given frequency to
         the 'left', 'right', or both sides (None)
@@ -2088,6 +2104,16 @@ def bdate_range(start=None, end=None, periods=None, freq='B', tz=None,
     rng : DatetimeIndex
     """
 
+    if is_string_like(freq) and freq.startswith('C'):
+        try:
+            freq = prefix_mapping[freq](holidays=holidays, weekmask=weekmask)
+        except (KeyError, TypeError):
+            msg = 'invalid custom frequency string: {freq}'.format(freq=freq)
+            raise ValueError(msg)
+    elif holidays or (weekmask != 'Mon Tue Wed Thu Fri'):
+        warnings.warn('a custom frequency string was not passed, ignoring '
+                      'parameters: holidays, weekmask', UserWarning)
+
     return DatetimeIndex(start=start, end=end, periods=periods,
                          freq=freq, tz=tz, normalize=normalize, name=name,
                          closed=closed, **kwargs)
@@ -2099,6 +2125,8 @@ def cdate_range(start=None, end=None, periods=None, freq='C', tz=None,
     Return a fixed frequency DatetimeIndex, with CustomBusinessDay as the
     default frequency
 
+    .. deprecated:: 0.21.0
+
     Parameters
     ----------
     start : string or datetime-like, default None
@@ -2137,6 +2165,9 @@ def cdate_range(start=None, end=None, periods=None, freq='C', tz=None,
     -------
     rng : DatetimeIndex
     """
+    warnings.warn("cdate_range is deprecated and will be removed in a future "
+                  "version, instead use bdate_range(..., freq='{freq}')"
+                  .format(freq=freq), FutureWarning, stacklevel=2)
 
     if freq == 'C':
         holidays = kwargs.pop('holidays', [])

pandas/core/indexes/datetimes.py

@@ -63,7 +63,7 @@ class TestPDApi(Base):
     # top-level functions
     funcs = ['bdate_range', 'concat', 'crosstab', 'cut',
              'date_range', 'interval_range', 'eval',
-             'factorize', 'get_dummies', 'cdate_range',
+             'factorize', 'get_dummies',
              'infer_freq', 'isna', 'isnull', 'lreshape',
              'melt', 'notna', 'notnull', 'offsets',
              'merge', 'merge_ordered', 'merge_asof',