deprecate cftime_range() in favor of date_range(use_cftime=True)

doc/whats-new.rst

@@ -29,7 +29,7 @@ Breaking changes
 
 Deprecations
 ~~~~~~~~~~~~
-
+xarray.cftime_range deprecated in favor of xarray.data_range(use_cftime=true)
 
 Bug fixes
 ~~~~~~~~~
@@ -42,6 +42,9 @@ Bug fixes
 - Use mean of min/max years as offset in calculation of datetime64 mean
   (:issue:`10019`, :pull:`10035`).
   By `Kai Mühlbauer <https://github.com/kmuehlbauer>`_.
+- Deprecate xr.cftime_range() in favor of xr.date_range(use_cftime=True)
+  (:issue:`9886`, :pull:`10024`).
+  By `Josh Kihm <https://github.com/maddogghoek>`_.
 
 
 Documentation

xarray/coding/cftime_offsets.py

@@ -855,15 +855,21 @@ def normalize_date(date):
     return date.replace(hour=0, minute=0, second=0, microsecond=0)
 
 
-def _maybe_normalize_date(date, normalize):
-    """Round datetime down to midnight if normalize is True."""
-    if normalize:
-        return normalize_date(date)
-    else:
+def _get_normalized_cfdate(date, calendar, normalize):
+    """convert to cf datetime and round down to midnight if normalize."""
+    if date is None:
         return date
 
+    cf_date = to_cftime_datetime(date, calendar)
+
+    return normalize_date(cf_date) if normalize else cf_date
+
+
+def _generate_date_range():
+    pass
 
-def _generate_linear_range(start, end, periods):
+
+def _generate_date_range(start, end, periods):
     """Generate an equally-spaced sequence of cftime.datetime objects between
     and including two dates (whose length equals the number of periods)."""
     if TYPE_CHECKING:
@@ -880,9 +886,9 @@ def _generate_linear_range(start, end, periods):
     )
 
 
-def _generate_range(start, end, periods, offset):
+def _generate_date_range_with_freq(start, end, periods, freq):
     """Generate a regular range of cftime.datetime objects with a
-    given time offset.
+    given frequency.
 
     Adapted from pandas.tseries.offsets.generate_range (now at
     pandas.core.arrays.datetimes._generate_range).
@@ -895,13 +901,15 @@ def _generate_range(start, end, periods, offset):
         End of range
     periods : int, or None
         Number of elements in the sequence
-    offset : BaseCFTimeOffset
-        An offset class designed for working with cftime.datetime objects
+    freq: str
+        Step size bewtween cftime.datetime objects. Not None.
 
     Returns
     -------
-    A generator object
+    A generator object of cftime.datetime objects
     """
+    offset = to_offset(freq)
+
     if start:
         # From pandas GH 56147 / 56832 to account for negative direction and
         # range bounds
@@ -949,7 +957,9 @@ def cftime_range(
     inclusive: InclusiveOptions = "both",
     calendar="standard",
 ) -> CFTimeIndex:
-    """Return a fixed frequency CFTimeIndex.
+    """DEPRECATED: use date_range(use_cftime=True) instead.
+
+    Return a fixed frequency CFTimeIndex.
 
     Parameters
     ----------
@@ -1103,6 +1113,9 @@ def cftime_range(
     objects associated with the specified calendar type, e.g.
 
     >>> xr.cftime_range(start="2000", periods=6, freq="2MS", calendar="noleap")
+    Traceback (most recent call last):
+        ...
+    DeprecationWarning: cftime_range() is deprecated, please use date_range(use_cftime=True) instead.
     CFTimeIndex([2000-01-01 00:00:00, 2000-03-01 00:00:00, 2000-05-01 00:00:00,
                  2000-07-01 00:00:00, 2000-09-01 00:00:00, 2000-11-01 00:00:00],
                 dtype='object', length=6, calendar='noleap', freq='2MS')
@@ -1118,52 +1131,95 @@ def cftime_range(
     --------
     pandas.date_range
     """
+    warnings.warn(
+        "cftime_range() is deprecated, please use date_range(use_cftime=True) instead.",
+        DeprecationWarning,
+        stacklevel=2,
+    )
 
+    return date_range(
+        start=start,
+        end=end,
+        periods=periods,
+        freq=freq,
+        normalize=normalize,
+        name=name,
+        inclusive=inclusive,
+        calendar=calendar,
+        use_cftime=True,
+    )
+
+
+def _cftime_range(
+    start=None,
+    end=None,
+    periods=None,
+    freq=None,
+    normalize=False,
+    name=None,
+    inclusive: InclusiveOptions = "both",
+    calendar="standard",
+) -> CFTimeIndex:
+    """Return a fixed frequency CFTimeIndex.
+
+    Parameters
+    ----------
+    start : str or cftime.datetime, optional
+        Left bound for generating dates.
+    end : str or cftime.datetime, optional
+        Right bound for generating dates.
+    periods : int, optional
+        Number of periods to generate.
+    freq : str or None, default: "D"
+        Frequency strings can have multiples, e.g. "5h" and negative values, e.g. "-1D".
+    normalize : bool, default: False
+        Normalize start/end dates to midnight before generating date range.
+    name : str, default: None
+        Name of the resulting index
+    inclusive : {"both", "neither", "left", "right"}, default "both"
+        Include boundaries; whether to set each bound as closed or open.
+    calendar : str, default: "standard"
+        Calendar type for the datetimes.
+
+    Returns
+    -------
+    CFTimeIndex
+
+    Notes
+    -----
+    see cftime_range
+    """
     if freq is None and any(arg is None for arg in [periods, start, end]):
         freq = "D"
 
     # Adapted from pandas.core.indexes.datetimes._generate_range.
     if count_not_none(start, end, periods, freq) != 3:
         raise ValueError(
-            "Of the arguments 'start', 'end', 'periods', and 'freq', three "
-            "must be specified at a time."
+            "Illegal combination of the arguments 'start', 'end', 'periods', "
+            "and 'freq' specified."
         )
 
-    if start is not None:
-        start = to_cftime_datetime(start, calendar)
-        start = _maybe_normalize_date(start, normalize)
-    if end is not None:
-        end = to_cftime_datetime(end, calendar)
-        end = _maybe_normalize_date(end, normalize)
+    start = _get_normalized_cfdate(start, calendar, normalize)
+    end = _get_normalized_cfdate(start, calendar, normalize)
 
     if freq is None:
-        dates = _generate_linear_range(start, end, periods)
-    else:
-        offset = to_offset(freq)
-        dates = np.array(list(_generate_range(start, end, periods, offset)))
-
-    if inclusive == "neither":
-        left_closed = False
-        right_closed = False
-    elif inclusive == "left":
-        left_closed = True
-        right_closed = False
-    elif inclusive == "right":
-        left_closed = False
-        right_closed = True
-    elif inclusive == "both":
-        left_closed = True
-        right_closed = True
+        dates = _generate_date_range(start, end, periods)
     else:
+        dates = np.array(
+            list(_generate_date_range_with_freq(start, end, periods, freq))
+        )
+
+    if inclusive not in InclusiveOptions:
         raise ValueError(
             f"Argument `inclusive` must be either 'both', 'neither', "
-            f"'left', 'right', or None.  Got {inclusive}."
+            f"'left', or 'right'.  Got {inclusive}."
         )
 
-    if not left_closed and len(dates) and start is not None and dates[0] == start:
-        dates = dates[1:]
-    if not right_closed and len(dates) and end is not None and dates[-1] == end:
-        dates = dates[:-1]
+    if len(dates) and inclusive != "both":
+        if inclusive != "left" and dates[0] == start:
+            dates = dates[1:]
+        if inclusive != "right" and dates[-1] == end:
+            dates = dates[:-1]
 
     return CFTimeIndex(dates, name=name)
 
@@ -1259,7 +1315,7 @@ def date_range(
             f"Invalid calendar {calendar} for pandas DatetimeIndex, try using `use_cftime=True`."
         )
 
-    return cftime_range(
+    return _cftime_range(
         start=start,
         end=end,
         periods=periods,

xarray/coding/cftimeindex.py

@@ -236,7 +236,7 @@ class CFTimeIndex(pd.Index):
 
     See Also
     --------
-    cftime_range
+    date_range
     """
 
     _data: np.ndarray
@@ -463,7 +463,7 @@ def shift(  # type: ignore[override]  # freq is typed Any, we are more precise
     ) -> Self:
         """Shift the CFTimeIndex a multiple of the given frequency.
 
-        See the documentation for :py:func:`~xarray.cftime_range` for a
+        See the documentation for :py:func:`~xarray.date_range` for a
         complete listing of valid frequency strings.
 
         Parameters
@@ -483,7 +483,7 @@ def shift(  # type: ignore[override]  # freq is typed Any, we are more precise
 
         Examples
         --------
-        >>> index = xr.cftime_range("2000", periods=1, freq="ME")
+        >>> index = xr.date_range("2000", periods=1, freq="ME", use_cftime=True)
         >>> index
         CFTimeIndex([2000-01-31 00:00:00],
                     dtype='object', length=1, calendar='standard', freq=None)
@@ -586,7 +586,9 @@ def to_datetimeindex(
 
         Examples
         --------
-        >>> times = xr.cftime_range("2000", periods=2, calendar="gregorian")
+        >>> times = xr.date_range(
+        ...     "2000", periods=2, calendar="gregorian", use_cftime=True
+        ... )
         >>> times
         CFTimeIndex([2000-01-01 00:00:00, 2000-01-02 00:00:00],
                     dtype='object', length=2, calendar='standard', freq=None)
@@ -652,8 +654,12 @@ def strftime(self, date_format):
 
         Examples
         --------
-        >>> rng = xr.cftime_range(
-        ...     start="2000", periods=5, freq="2MS", calendar="noleap"
+        >>> rng = xr.date_range(
+        ...     start="2000",
+        ...     periods=5,
+        ...     freq="2MS",
+        ...     calendar="noleap",
+        ...     use_cftime=True,
         ... )
         >>> rng.strftime("%B %d, %Y, %r")
         Index(['January 01, 2000, 12:00:00 AM', 'March 01, 2000, 12:00:00 AM',

xarray/core/dataarray.py

@@ -5618,7 +5618,7 @@ def map_blocks(
         ...     clim = gb.mean(dim="time")
         ...     return gb - clim
         ...
-        >>> time = xr.cftime_range("1990-01", "1992-01", freq="ME")
+        >>> time = xr.date_range("1990-01", "1992-01", freq="ME", use_cftime=True)
         >>> month = xr.DataArray(time.month, coords={"time": time}, dims=["time"])
         >>> np.random.seed(123)
         >>> array = xr.DataArray(

xarray/core/dataset.py

@@ -9024,7 +9024,7 @@ def map_blocks(
         ...     clim = gb.mean(dim="time")
         ...     return gb - clim
         ...
-        >>> time = xr.cftime_range("1990-01", "1992-01", freq="ME")
+        >>> time = xr.date_range("1990-01", "1992-01", freq="ME", use_cftime=True)
         >>> month = xr.DataArray(time.month, coords={"time": time}, dims=["time"])
         >>> np.random.seed(123)
         >>> array = xr.DataArray(

xarray/core/parallel.py

@@ -296,7 +296,7 @@ def map_blocks(
     ...     clim = gb.mean(dim="time")
     ...     return gb - clim
     ...
-    >>> time = xr.cftime_range("1990-01", "1992-01", freq="ME")
+    >>> time = xr.date_range("1990-01", "1992-01", freq="ME", use_cftime=True)
     >>> month = xr.DataArray(time.month, coords={"time": time}, dims=["time"])
     >>> np.random.seed(123)
     >>> array = xr.DataArray(