cftime - CF-Compliant Time Handling

Common errors

• Failed building wheel for cftime

  cause This error typically occurs during installation on Linux systems when the required C/C++ compilers (like gcc) and Python development headers are missing, which are necessary to compile `cftime`'s C extensions.
  fix Install the necessary build tools and Python development headers. For Debian/Ubuntu-based systems: `sudo apt-get update && sudo apt-get install python3-dev gcc`. For systems using Anaconda/Miniconda, use `conda install cftime` which provides pre-compiled binaries.

• TypeError: unsupported operand type(s) for +: 'cftime._cftime.DatetimeNoLeap' and 'datetime.timedelta'

  cause Direct arithmetic operations with `datetime.timedelta` are not universally supported by all `cftime.datetime` calendar types, especially non-standard ones, as `datetime.timedelta` assumes a standard Gregorian-like calendar system. The `cftime.datetime` instances are calendar-aware and require specific methods for time arithmetic.
  fix For standard calendar types, ensure the `cftime.datetime` object is calendar-aware and try `cftime.datetime`'s own arithmetic or conversion methods. For non-standard calendars, it's often best to convert the `cftime.datetime` object to a numerical representation (e.g., days/seconds since an epoch) for arithmetic operations, and then convert back to a `cftime.datetime` object.

• TypeError: <class 'cftime._cftime.Datetime360Day'> is not convertible to datetime

  cause Python's native `datetime.datetime` objects only support standard Gregorian and Julian calendars. `cftime.datetime` instances representing non-standard calendars (like '360_day', 'noleap', '365_day') cannot be directly converted to `datetime.datetime` because the native Python object lacks the capability to represent these calendar systems.
  fix If a native `datetime.datetime` object is absolutely required, you must first convert the `cftime.datetime` object to a compatible calendar (e.g., 'standard' or 'proleptic_gregorian') if the conversion is meaningful for your data, or manually extract its components (year, month, day, etc.) and handle them separately. The `cftime.num2pydate` function can convert `cftime.datetime` objects to Python `datetime` objects if the calendar is compatible.

• ValueError: given calendar 'invalid_calendar_name' is not a supported calendar

  cause This error occurs when the `calendar` argument provided to `cftime.datetime` or related functions does not match one of the predefined and supported CF-compliant calendar strings.
  fix Use one of the valid CF-compliant calendar strings. The supported calendars are: `'standard'`, `'gregorian'`, `'proleptic_gregorian'`, `'noleap'`, `'365_day'`, `'360_day'`, `'julian'`, `'all_leap'`, `'366_day'`.

Warnings

• breaking Since `cftime` v1.1.0, `cftime.num2date` defaults to returning `cftime.datetime` instances for all calendars. Previously, it would return standard `python datetime` objects when possible.
  Fix: If you require standard `python datetime` objects, use the `cftime.num2pydate` function instead. Otherwise, update your code to expect `cftime.datetime` objects.
• breaking In `cftime` v1.2.0, the default `calendar` argument for `cftime.date2num` changed from `'standard'` to `None`. This means the calendar is now inferred from the input `datetime` object(s).
  Fix: Always explicitly specify the `calendar` argument in `cftime.date2num` calls to ensure consistent behavior, e.g., `cftime.date2num(dates, units, calendar='gregorian')`.
• breaking The legacy functions `cftime.utime`, `cftime.JulianDayFromDate`, and `cftime.DateFromJulianDay` were removed in v1.5.0.
  Fix: Replace usage of `JulianDayFromDate` and `DateFromJulianFromDate` with `cftime.datetime.toordinal` and `cftime.datetime.fromordinal` respectively. `cftime.utime` no longer has a direct replacement and refactoring may be needed based on its specific usage.
• deprecated The direct use of calendar-specific subclasses (e.g., `cftime.DatetimeNoLeap`) in operations like `cftime.num2date`, `cftime.datetime.__add__`, and `cftime.datetime.__sub__` is deprecated and will be removed in a future release.
  Fix: Prefer using the base `cftime.datetime` class with the `calendar` keyword argument, e.g., `cftime.datetime(2000, 1, 1, calendar='noleap')`.
• gotcha Performance may degrade when performing calculations with `cftime.datetime` instances that represent dates extremely far from the 1970-01-01 reference date. This is due to the complex leap year calculations across various supported calendars.
  Fix: Be mindful of performance for very distant dates. For highly performance-sensitive applications with extreme date ranges, consider profiling and optimizing accordingly, or ensuring your time 'units' define an origin closer to your data range.
• gotcha The 'standard' calendar explicitly marks dates between October 5 and October 14, 1582, as invalid. These dates are skipped to account for the historical Julian-to-Gregorian calendar transition.
  Fix: If working with historical dates that span or predate this transition and require continuous date representation (e.g., for modeling without a break), use the 'proleptic_gregorian' calendar which applies the Gregorian rules universally and avoids this gap.

Install

• pip install cftime Install with pip

Imports

• datetime

  from cftime import datetime

• num2date

  from cftime import num2date

• date2num

  from cftime import date2num

• num2pydate
  wrong:

  from cftime import num2date; # if expecting python datetime objects

  correct:

  from cftime import num2pydate

  num2date now returns cftime.datetime by default since v1.1.0; use num2pydate for native python datetime objects.

Quickstart

This quickstart demonstrates how to create `cftime.datetime` objects, convert them to numeric representations using `date2num`, and convert numeric times back to `cftime.datetime` objects using `num2date`, showcasing different calendar types.

import cftime
import numpy as np

# Create a cftime.datetime object with a specific calendar
date_obj = cftime.datetime(2000, 2, 29, 12, 0, 0, calendar='gregorian')
print(f"Created cftime.datetime (Gregorian): {date_obj}")

# Convert to a numeric representation (e.g., 'days since 2000-01-01')
units = "days since 2000-01-01"
numeric_time = cftime.date2num(date_obj, units=units, calendar=date_obj.calendar)
print(f"Numeric time ({units}): {numeric_time}")

# Convert back to a cftime.datetime object
reconstructed_date = cftime.num2date(numeric_time, units=units, calendar=date_obj.calendar)
print(f"Reconstructed cftime.datetime: {reconstructed_date}")

# Example with a non-standard calendar (360_day has Feb 30)
date_360_day = cftime.datetime(2000, 2, 30, calendar='360_day')
print(f"360-day calendar date: {date_360_day}")