API

class cftime.datetime(int year, int month, int day, int hour=0, int minute=0, int second=0, int microsecond=0, int dayofwk=-1, int dayofyr=-1, calendar='standard')

Bases: object

The base class implementing most methods of datetime classes that mimic datetime.datetime but support calendars other than the proleptic Gregorial calendar.

isoformat(self, sep='T', timespec='auto')
replace(self, **kwargs)

Return datetime with new specified fields.

strftime(self, format=None)

Return a string representing the date, controlled by an explicit format string. For a complete list of formatting directives, see section ‘strftime() and strptime() Behavior’ in the base Python documentation.

timetuple(self)

Return a time.struct_time such as returned by time.localtime(). The DST flag is -1. d.timetuple() is equivalent to time.struct_time((d.year, d.month, d.day, d.hour, d.minute, d.second, d.weekday(), yday, dst)), where yday is the day number within the current year starting with 1 for January 1st.

cftime.date2num(dates, units, calendar='standard')

Return numeric time values given datetime objects. The units of the numeric time values are described by the units argument and the calendar keyword. The datetime objects must be in UTC with no time-zone offset. If there is a time-zone offset in units, it will be applied to the returned numeric values.

dates: A datetime object or a sequence of datetime objects. The datetime objects should not include a time-zone offset.

units: a string of the form <time units> since <reference time> describing the time units. <time units> can be days, hours, minutes, seconds, milliseconds or microseconds. <reference time> is the time origin. months_since is allowed only for the 360_day calendar.

calendar: describes the calendar used in the time calculations. All the values currently defined in the [CF metadata convention](http://cfconventions.org) Valid calendars ‘standard’, ‘gregorian’, ‘proleptic_gregorian’ ‘noleap’, ‘365_day’, ‘360_day’, ‘julian’, ‘all_leap’, ‘366_day’. Default is ‘standard’, which is a mixed Julian/Gregorian calendar.

returns a numeric time value, or an array of numeric time values with approximately 1 microsecond accuracy.

cftime.num2date(times, units, calendar='standard', only_use_cftime_datetimes=True, only_use_python_datetimes=False)

Return datetime objects given numeric time values. The units of the numeric time values are described by the units argument and the calendar keyword. The returned datetime objects represent UTC with no time-zone offset, even if the specified units contain a time-zone offset.

times: numeric time values.

units: a string of the form <time units> since <reference time> describing the time units. <time units> can be days, hours, minutes, seconds, milliseconds or microseconds. <reference time> is the time origin. months_since is allowed only for the 360_day calendar.

calendar: describes the calendar used in the time calculations. All the values currently defined in the [CF metadata convention](http://cfconventions.org) Valid calendars ‘standard’, ‘gregorian’, ‘proleptic_gregorian’ ‘noleap’, ‘365_day’, ‘360_day’, ‘julian’, ‘all_leap’, ‘366_day’. Default is ‘standard’, which is a mixed Julian/Gregorian calendar.

only_use_cftime_datetimes: if False, python datetime.datetime objects are returned from num2date where possible; if True dates which subclass cftime.datetime are returned for all calendars. Default True.

only_use_python_datetimes: always return python datetime.datetime objects and raise an error if this is not possible. Ignored unless only_use_cftime_datetimes=False. Default False.

returns a datetime instance, or an array of datetime instances with microsecond accuracy, if possible.

*Note*: If only_use_cftime_datetimes=False and use_only_python_datetimes=False, the datetime instances returned are ‘real’ python datetime objects if calendar=’proleptic_gregorian’, or calendar=’standard’ or ‘gregorian’ and the date is after the breakpoint between the Julian and Gregorian calendars (1582-10-15). Otherwise, they are ctime.datetime objects which support some but not all the methods of native python datetime objects. The datetime instances do not contain a time-zone offset, even if the specified units contains one.

cftime.num2pydate(times, units, calendar='standard')

Always returns python datetime.datetime objects and raise an error if this is not possible.

Same as num2date(times,units,calendar,only_use_cftime_datetimes=False,only_use_python_datetimes=True)

cftime.date2index(dates, nctime, calendar=None, select='exact')

Return indices of a netCDF time variable corresponding to the given dates.

dates: A datetime object or a sequence of datetime objects. The datetime objects should not include a time-zone offset.

nctime: A netCDF time variable object. The nctime object must have a units attribute.

calendar: describes the calendar used in the time calculations. All the values currently defined in the [CF metadata convention](http://cfconventions.org) Valid calendars ‘standard’, ‘gregorian’, ‘proleptic_gregorian’ ‘noleap’, ‘365_day’, ‘360_day’, ‘julian’, ‘all_leap’, ‘366_day’. Default is ‘standard’, which is a mixed Julian/Gregorian calendar. If calendar is None, its value is given by nctime.calendar or standard if no such attribute exists.

select: ‘exact’, ‘before’, ‘after’, ‘nearest’ The index selection method. exact will return the indices perfectly matching the dates given. before and after will return the indices corresponding to the dates just before or just after the given dates if an exact match cannot be found. nearest will return the indices that correspond to the closest dates.

returns an index (indices) of the netCDF time variable corresponding to the given datetime object(s).

cftime.JulianDayFromDate(date, calendar='standard')

JulianDayFromDate(date, calendar=’standard’)

creates a Julian Day from a ‘datetime-like’ object. Returns the fractional Julian Day (approximately 100 microsecond accuracy).

if calendar=’standard’ or ‘gregorian’ (default), Julian day follows Julian Calendar on and before 1582-10-5, Gregorian calendar after 1582-10-15.

if calendar=’proleptic_gregorian’, Julian Day follows gregorian calendar.

if calendar=’julian’, Julian Day follows julian calendar.

class cftime.DatetimeJulian(*args, **kwargs)

Bases: cftime._cftime.datetime

Phony datetime object which mimics the python datetime object, but uses the “julian” calendar.

class cftime.DatetimeProlepticGregorian(*args, **kwargs)

Bases: cftime._cftime.datetime

Phony datetime object which mimics the python datetime object, but allows for dates that don’t exist in the proleptic gregorian calendar.

Supports timedelta operations by overloading + and -.

Has strftime, timetuple, replace, __repr__, and __str__ methods. The format of the string produced by __str__ is controlled by self.format (default %Y-%m-%d %H:%M:%S). Supports comparisons with other datetime instances using the same calendar; comparison with native python datetime instances is possible for cftime.datetime instances using ‘gregorian’ and ‘proleptic_gregorian’ calendars.

Instance variables are year,month,day,hour,minute,second,microsecond,dayofwk,dayofyr, format, and calendar.

class cftime.DatetimeNoLeap(*args, **kwargs)

Bases: cftime._cftime.datetime

Phony datetime object which mimics the python datetime object, but uses the “noleap” (“365_day”) calendar.

class cftime.DatetimeAllLeap(*args, **kwargs)

Bases: cftime._cftime.datetime

Phony datetime object which mimics the python datetime object, but uses the “all_leap” (“366_day”) calendar.

class cftime.DatetimeGregorian(*args, **kwargs)

Bases: cftime._cftime.datetime

Phony datetime object which mimics the python datetime object, but uses the mixed Julian-Gregorian (“standard”, “gregorian”) calendar.

The last date of the Julian calendar is 1582-10-4, which is followed by 1582-10-15, using the Gregorian calendar.

Instances using the date after 1582-10-15 can be compared to datetime.datetime instances and used to compute time differences (datetime.timedelta) by subtracting a DatetimeGregorian instance from a datetime.datetime instance or vice versa.

cftime.DateFromJulianDay(JD, calendar='standard', only_use_cftime_datetimes=True, return_tuple=False)

returns a ‘datetime-like’ object given Julian Day. Julian Day is a fractional day with approximately 100 microsecond accuracy.

if calendar=’standard’ or ‘gregorian’ (default), Julian day follows Julian Calendar on and before 1582-10-5, Gregorian calendar after 1582-10-15.

if calendar=’proleptic_gregorian’, Julian Day follows gregorian calendar.

if calendar=’julian’, Julian Day follows julian calendar.

If only_use_cftime_datetimes is set to True, then cftime.datetime objects are returned for all calendars. Otherwise the datetime object is a native python datetime object if the date falls in the Gregorian calendar (i.e. calendar=’proleptic_gregorian’, or calendar = ‘standard’/’gregorian’ and the date is after 1582-10-15).

cftime.time2index(times, nctime, calendar=None, select='exact')

Return indices of a netCDF time variable corresponding to the given times.

times: A numeric time or a sequence of numeric times.

nctime: A netCDF time variable object. The nctime object must have a C{units} attribute. The entries are assumed to be stored in increasing order.

calendar: Describes the calendar used in the time calculation. Valid calendars C{‘standard’, ‘gregorian’, ‘proleptic_gregorian’ ‘noleap’, ‘365_day’, ‘360_day’, ‘julian’, ‘all_leap’, ‘366_day’}. Default is C{‘standard’}, which is a mixed Julian/Gregorian calendar If C{calendar} is None, its value is given by C{nctime.calendar} or C{standard} if no such attribute exists.

select: ‘exact’, ‘before’, ‘after’, ‘nearest’ The index selection method. C{exact} will return the indices perfectly matching the times given. C{before} and C{after} will return the indices corresponding to the times just before or just after the given times if an exact match cannot be found. C{nearest} will return the indices that correspond to the closest times.