Class CFDatetimeCoder

xarray/coding/times.py:1355–1428

Coder for CF Datetime coding. Parameters ---------- use_cftime : bool, optional 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

class CFDatetimeCoder(VariableCoder):
    """Coder for CF Datetime coding.

    Parameters
    ----------
    use_cftime : bool, optional
        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`` 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`` objects.  If False, always
        decode times to ``np.datetime64`` objects; if this is not possible
        raise an error.
        May not be supported by all the backends.
    time_unit : PDDatetimeUnitOptions
          Target resolution when decoding dates. Defaults to "ns".
    """

    def __init__(
        self,
        use_cftime: bool | None = None,
        time_unit: PDDatetimeUnitOptions = "ns",
    ) -> None:
        self.use_cftime = use_cftime
        self.time_unit = time_unit

    def encode(self, variable: Variable, name: T_Name = None) -> Variable:
        if np.issubdtype(variable.dtype, np.datetime64) or contains_cftime_datetimes(
            variable
        ):
            dims, data, attrs, encoding = unpack_for_encoding(variable)

            units = encoding.pop("units", None)
            calendar = encoding.pop("calendar", None)
            dtype = encoding.get("dtype", None)

            # in the case of packed data we need to encode into
            # float first, the correct dtype will be established
            # via CFScaleOffsetCoder/CFMaskCoder
            if "add_offset" in encoding or "scale_factor" in encoding:
                dtype = data.dtype if data.dtype.kind == "f" else "float64"
            (data, units, calendar) = encode_cf_datetime(data, units, calendar, dtype)

            safe_setitem(attrs, "units", units, name=name)
            safe_setitem(attrs, "calendar", calendar, name=name)

            return Variable(dims, data, attrs, encoding, fastpath=True)
        else:
            return variable

    def decode(self, variable: Variable, name: T_Name = None) -> Variable:
        units = variable.attrs.get("units", None)
        if isinstance(units, str) and "since" in units:
            dims, data, attrs, encoding = unpack_for_decoding(variable)

            units = pop_to(attrs, encoding, "units")