split out CFDatetimeCoder, deprecate use_cftime as kwarg

[kmuehlbauer]

• Tests added
• User visible changes (including notable bug fixes) are documented in whats-new.rst
• New functions/methods are listed in api.rst

This makes something like this possible:

import xarray as xr
from xarray.coders import CFDatetimeCoder
# available with this PR
ds = xr.open_mfdataset(..., decode_times=CFDatetimeCoder(use_cftime=True))
# available with #9618
ds = xr.open_mfdataset(..., decode_times=CFDatetimeCoder(time_unit="s"))

[dcherian]

I like this but since this is adding public API, can you open an issue and see if everyone is on board please

[kmuehlbauer]

@dcherian Thanks for reviewing, addressed along your comments/suggestions. I've added a comment to #4490 for more visibility, hope that's sufficient.

[mathause]

Can you explicitely write how to change this in the deprecation warning? As is I don't find it obvious what users have to do. ('Use decode_times=xr.coders.CFDatetimeCoder(use_cftime=True) instead').

I am also a bit surprised that the CFDateTimeCoder does not imply use_cftime=True - should that be named DateTimeCoder? (or did I miss this discusdion?)

Is the use of DeprecationWarning intentional? That's still silent in certain situations, right?

(Removing an arg is always nice but I use this a lot and its much more verbose...)

[kmuehlbauer]

@mathause Thanks for sharing your concerns and suggestions.

Can you explicitely write how to change this in the deprecation warning? As is I don't find it obvious what users have to do. ('Use decode_times=xr.coders.CFDatetimeCoder(use_cftime=True) instead').

Yes, this is a bit sparse, how is it with:

import xarray as xr
time_coder = xr.coders.CFDatetimeCoder(use_cftime=True)
ds = xr.open_dataset(decode_times=time_coder)

I am also a bit surprised that the CFDateTimeCoder does not imply use_cftime=True - should that be named DateTimeCoder? (or did I miss this discusdion?)

So the current state of affairs is:

The default state of open_dataset kwarg decode_times depends on the backend, for most backends this is True. This will trying to decode datetimes into numpy datetime64 (pandas DatetimeIndex), if the on-disk datetimes are in the ns-representable time-range and a standard calendar is used. If this fails, cftime is used resulting in a CFTimeIndex. Setting use_cftime=True means to use the cftime-package for decoding anyway. This will result in a CFTimeIndex. In most cases (standard calendar/ proleptic gregorian) cftime is not needed to correctly decode according CF into numpy datetime64. Does that make sense?

Is the use of DeprecationWarning intentional? That's still silent in certain situations, right?

As the current behaviour is preserved, we might skip the DeprecationWarning for now until all coders have been edited to conform to some solution which originated from #4490. In the last dev meeting @TomNicholas added an item to the agenda moving the cf coders into a new package (xref https://github.com/xarray-contrib/cf-codecs and cc @rabernat). So this would be a first step into this direction.

I'll rework the DeprecationWarning to more explicit in what to do, but we should decide whether we want to warn from now or postpone this until we have a clear way of how to do things.

[kmuehlbauer]

Suggested change

	"'decode_times' kwarg.",
	"'decode_times' kwarg.\n",
	"Example usage:\n",
	" time_coder = xr.coders.CFDatetimeCoder(use_cftime=True)\n",
	" ds = xr.open_dataset(decode_times=time_coder)\n",

[kmuehlbauer]

@mathause Would that help in the DeprecationWarning?