- Update cftime_range example to expect deprecation warning.

- update other examples that call cftime_range to use date_range(use_cftime=True) instead

Issue pydata#9886

Author: maddogghoek

xarray/coding/cftime_offsets.py

@@ -1113,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')

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(