Note that use_cftime is only relevant for standard calendar dates

Author: spencerkclark

doc/whats-new.rst

@@ -70,12 +70,12 @@ Enhancements
   (:issue:`2688`). By `Spencer Clark <https://github.com/spencerkclark>`_.
 - :py:meth:`~xarray.open_dataset` now accepts a ``use_cftime`` argument, which
   can be used to require that ``cftime.datetime`` objects are always used, or
-  never used when decoding dates.  This can be used to ensure consistent date
-  types are returned when using :py:meth:`~xarray.open_mfdataset`
-  (:issue:`1263`) and/or to silence serialization warnings raised if dates from
-  a standard calendar are found to be outside the
-  :py:class:`pandas.Timestamp`-valid range (:issue:`2754`).  By `Spencer Clark
-  <https://github.com/spencerkclark>`_. 
+  never used when decoding dates encoded with a standard calendar.  This can be
+  used to ensure consistent date types are returned when using
+  :py:meth:`~xarray.open_mfdataset` (:issue:`1263`) and/or to silence
+  serialization warnings raised if dates from a standard calendar are found to
+  be outside the :py:class:`pandas.Timestamp`-valid range (:issue:`2754`).  By
+  `Spencer Clark <https://github.com/spencerkclark>`_. 
 
 Bug fixes
 ~~~~~~~~~

xarray/backends/api.py

@@ -232,12 +232,15 @@ def open_dataset(filename_or_obj, group=None, decode_cf=True,
         may be useful when backend options would improve performance or
         allow user control of dataset processing.
     use_cftime: bool, optional
-        If None (default), attempt to decode times to ``np.datetime64[ns]``
-        objects; if this is not possible, decode times to ``cftime.datetime``
-        objects. If True, always decode times to ``cftime.datetime`` objects,
-        regardless of whether or not they can be represented using
-        ``np.datetime64[ns]`` objects.  If False, always decode times to
-        ``np.datetime64[ns]`` objects; if this is not possible raise an error.
+        Only relevant if encoded dates come from a standard calendar
+        (e.g. 'gregorian', 'proleptic_gregorian', 'standard', or not
+        specified).  If None (default), attempt to decode times to
+        ``np.datetime64[ns]`` objects; if this is not possible, decode times to
+        ``cftime.datetime`` objects. If True, always decode times to
+        ``cftime.datetime`` objects, regardless of whether or not they can be
+        represented using ``np.datetime64[ns]`` objects.  If False, always
+        decode times to ``np.datetime64[ns]`` objects; if this is not possible
+        raise an error.
 
     Returns
     -------
@@ -437,12 +440,15 @@ def open_dataarray(filename_or_obj, group=None, decode_cf=True,
         may be useful when backend options would improve performance or
         allow user control of dataset processing.
     use_cftime: bool, optional
-        If None (default), attempt to decode times to ``np.datetime64[ns]``
-        objects; if this is not possible, decode times to ``cftime.datetime``
-        objects. If True, always decode times to ``cftime.datetime`` objects,
-        regardless of whether or not they can be represented using
-        ``np.datetime64[ns]`` objects.  If False, always decode times to
-        ``np.datetime64[ns]`` objects; if this is not possible raise an error.
+        Only relevant if encoded dates come from a standard calendar
+        (e.g. 'gregorian', 'proleptic_gregorian', 'standard', or not
+        specified).  If None (default), attempt to decode times to
+        ``np.datetime64[ns]`` objects; if this is not possible, decode times to
+        ``cftime.datetime`` objects. If True, always decode times to
+        ``cftime.datetime`` objects, regardless of whether or not they can be
+        represented using ``np.datetime64[ns]`` objects.  If False, always
+        decode times to ``np.datetime64[ns]`` objects; if this is not possible
+        raise an error.
 
     Notes
     -----

xarray/conventions.py

@@ -271,12 +271,15 @@ def decode_cf_variable(name, var, concat_characters=True, mask_and_scale=True,
         array. Passed as an argument because we need to look at the full
         dataset to figure out if this is appropriate.
     use_cftime: bool, optional
-        If None (default), attempt to decode times to ``np.datetime64[ns]``
-        objects; if this is not possible, decode times to ``cftime.datetime``
-        objects. If True, always decode times to ``cftime.datetime`` objects,
-        regardless of whether or not they can be represented using
-        ``np.datetime64[ns]`` objects.  If False, always decode times to
-        ``np.datetime64[ns]`` objects; if this is not possible raise an error.
+        Only relevant if encoded dates come from a standard calendar
+        (e.g. 'gregorian', 'proleptic_gregorian', 'standard', or not
+        specified).  If None (default), attempt to decode times to
+        ``np.datetime64[ns]`` objects; if this is not possible, decode times to
+        ``cftime.datetime`` objects. If True, always decode times to
+        ``cftime.datetime`` objects, regardless of whether or not they can be
+        represented using ``np.datetime64[ns]`` objects.  If False, always
+        decode times to ``np.datetime64[ns]`` objects; if this is not possible
+        raise an error.
 
     Returns
     -------
@@ -441,12 +444,15 @@ def decode_cf(obj, concat_characters=True, mask_and_scale=True,
         dataset. This may be useful to drop variables with problems or
         inconsistent values.
     use_cftime: bool, optional
-        If None (default), attempt to decode times to ``np.datetime64[ns]``
-        objects; if this is not possible, decode times to ``cftime.datetime``
-        objects. If True, always decode times to ``cftime.datetime`` objects,
-        regardless of whether or not they can be represented using
-        ``np.datetime64[ns]`` objects.  If False, always decode times to
-        ``np.datetime64[ns]`` objects; if this is not possible raise an error.
+        Only relevant if encoded dates come from a standard calendar
+        (e.g. 'gregorian', 'proleptic_gregorian', 'standard', or not
+        specified).  If None (default), attempt to decode times to
+        ``np.datetime64[ns]`` objects; if this is not possible, decode times to
+        ``cftime.datetime`` objects. If True, always decode times to
+        ``cftime.datetime`` objects, regardless of whether or not they can be
+        represented using ``np.datetime64[ns]`` objects.  If False, always
+        decode times to ``np.datetime64[ns]`` objects; if this is not possible
+        raise an error.
 
     Returns
     -------