Note that use_cftime is only relevant for standard calendar dates

spencerkclark · spencerkclark · commit 52866a81c2b5 · 2019-02-13T17:04:05.000-05:00
diff --git a/doc/whats-new.rst b/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
 ~~~~~~~~~
diff --git a/xarray/backends/api.py b/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
     -----
diff --git a/xarray/conventions.py b/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
     -------
