Implement time_unit option for decode_cf_timedelta

[spencerkclark]

My main remaining concern with pydata#9618 is that timedelta decoding / encoding is inconsistent with what is done for datetimes, i.e.:

• It is possible to decode into non-nanosecond resolution timedelta values without specifying the time_unit, which would be a breaking change, e.g.:

>>> times = [1, 2, 3]
>>> xr.coding.times.decode_cf_timedelta(times, "seconds")
array([1, 2, 3], dtype='timedelta64[s]')

• Encoding large non-nanosecond resolution timedelta values can silently lead to overflow, e.g.:

>>> time = np.timedelta64(300 * 365, "D").astype("timedelta64[s]")
>>> xr.coding.times.encode_cf_timedelta(time)
(array(-9223372036854775808), 'nanoseconds')

I have not yet gone the step of exposing the option to change the time_unit through CFTimedeltaCoder through the decode_timedelta argument, but this PR implements what I think is needed to bring the internals of non-nanosecond timedelta decoding / encoding up to speed with datetime decoding / encoding (I can do that later if you want).

Similar to datetime decoding, the default behavior is to always return nanosecond resolution values, or raise an error if this would lead to overflow. As in datetime decoding, if a time_unit is specified that is coarser than the encoded timedeltas, the time_unit is updated to prevent precision loss.

I added a few tests, which exercise this aspect of the code, including some that check overflow-safety and others that check we can accurately roundtrip large timedeltas. With these changes the above examples work as expected:

>>> times = [1, 2, 3]
>>> xr.coding.times.decode_cf_timedelta(times, "seconds")
array([1000000000, 2000000000, 3000000000], dtype='timedelta64[ns]')

>>> time = np.timedelta64(300 * 365, "D").astype("timedelta64[s]")
>>> xr.coding.times.encode_cf_timedelta(time)
(array(109500), 'days')

[kmuehlbauer]

That's great @spencerkclark! 👍 💯 This should definitely be part of pydata#9618 for sake of consistency and backwards compatibility. So I'm inclined to merge this.

[spencerkclark]

Sounds good! We can address adding time_unit to the CFTimedeltaCoder once pydata#9618 is merged.