API

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

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 to be used in the time calculations. All the values currently defined in the CF metadata convention are supported. Valid calendars ‘standard’, ‘gregorian’, ‘proleptic_gregorian’ ‘noleap’, ‘365_day’, ‘360_day’, ‘julian’, ‘all_leap’, ‘366_day’. Default is None which means the calendar associated with the first input datetime instance will be used.

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.

has_year_zero: if set to True, astronomical year numbering is used and the year zero exists. If set to False for real-world calendars, then historical year numbering is used and the year 1 is preceded by year -1 and no year zero exists. The defaults are set to conform with CF version 1.9 conventions (False for ‘julian’, ‘gregorian’/’standard’, True for ‘proleptic_gregorian’ (ISO 8601) and True for the idealized calendars ‘noleap’/’365_day’, ‘360_day’, 366_day’/’all_leap’) The defaults can only be over-ridden for the real-world calendars, for the the idealized calendars the year zero always exists and the has_year_zero kwarg is ignored. This kwarg is not needed to define calendar systems allowed by CF (the calendar-specific defaults do this).

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

cftime.date2num(dates, units, calendar=None, has_year_zero=None, longdouble=False)

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. They can be either native python datetime instances (which use the proleptic gregorian calendar) or cftime.datetime instances.

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 and common_years since is allowed only for the 365_day calendar.

calendar: describes the calendar to be used in the time calculations. All the values currently defined in the CF metadata convention are supported. Valid calendars ‘standard’, ‘gregorian’, ‘proleptic_gregorian’ ‘noleap’, ‘365_day’, ‘360_day’, ‘julian’, ‘all_leap’, ‘366_day’. Default is None which means the calendar associated with the first input datetime instance will be used.

has_year_zero: If set to True, astronomical year numbering is used and the year zero exists. If set to False for real-world calendars, then historical year numbering is used and the year 1 is preceded by year -1 and no year zero exists. The defaults are set to conform with CF version 1.9 conventions (False for ‘julian’, ‘gregorian’/’standard’, True for ‘proleptic_gregorian’ (ISO 8601) and True for the idealized calendars ‘noleap’/’365_day’, ‘360_day’, 366_day’/’all_leap’) Note that CF v1.9 does not specifically mention whether year zero is allowed in the proleptic_gregorian calendar, but ISO-8601 has a year zero so we have adopted this as the default. The defaults can only be over-ridden for the real-world calendars, for the the idealized calendars the year zero always exists and the has_year_zero kwarg is ignored. This kwarg is not needed to define calendar systems allowed by CF (the calendar-specific defaults do this).

longdouble: If set True, output is in the long double float type (numpy.float128) instead of float (numpy.float64), allowing microsecond accuracy when converting a time value to a date and back again. Otherwise this is only possible if the discretization of the time variable is an integer multiple of the units.

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

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=u'standard', has_year_zero=None)

Bases: object

This class mimics datetime.datetime but support calendars other than the proleptic Gregorian calendar.

Supports timedelta operations by overloading +/-, and comparisons with other instances (even if they use different calendars).

Comparison with native python datetime instances is possible for cftime.datetime instances using ‘gregorian’ and ‘proleptic_gregorian’ calendars.

All the calendars currently defined in the CF metadata convention are supported. Valid calendars are ‘standard’, ‘gregorian’, ‘proleptic_gregorian’ ‘noleap’, ‘365_day’, ‘360_day’, ‘julian’, ‘all_leap’, ‘366_day’. Default is ‘standard’, which is a mixed Julian/Gregorian calendar. ‘standard’ and ‘gregorian’ are synonyms, as are ‘all_leap’/’366_day’ and ‘noleap’/’365_day’.

If the calendar kwarg is set to a blank string (‘’) or None (the default is ‘standard’) the instance will not be calendar-aware and some methods will not work.

If the has_year_zero kwarg is set to True, astronomical year numbering is used and the year zero exists. If set to False for real-world calendars, then historical year numbering is used and the year 1 is preceded by year -1 and no year zero exists. The defaults are set to conform with CF version 1.9 conventions (False for ‘julian’, ‘gregorian’/’standard’, True for ‘proleptic_gregorian’ (ISO 8601) and True for the idealized calendars ‘noleap’/’365_day’, ‘360_day’, 366_day’/’all_leap’) The defaults can only be over-ridden for the real-world calendars, for the the idealized calendars the year zero always exists and the has_year_zero kwarg is ignored. This kwarg is not needed to define calendar systems allowed by CF (the calendar-specific defaults do this).

Has isoformat, strftime, timetuple, replace, dayofwk, dayofyr, daysinmonth, __repr__,__format__, __add__, __sub__, __str__ and comparison methods.

dayofwk, dayofyr, daysinmonth, __add__ and __sub__ only work for calendar-aware instances.

The default format of the string produced by strftime is controlled by self.format (default %Y-%m-%d %H:%M:%S).

change_calendar(self, calendar, has_year_zero=None)

static fromordinal(jday, calendar='standard', has_year_zero=None)

Create a datetime instance from a julian day ordinal, calendar and (optionally) year zero convention (inverse of toordinal). The Julian day number is the number of days since noon UTC January 1, 4713 in the proleptic julian calendar with no year zero (November 24, 4713 in the proleptic gregorian calendar that includes the year zero). For idealized calendars, the origin is noon UTC of the year zero.

isoformat(self, sep='T', timespec='auto')

ISO date representation

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.

static strptime(datestring, format, calendar='standard', has_year_zero=None)

Return a datetime corresponding to date_string, parsed according to format, with a specified calendar and year zero convention. The format directives ‘y’,’Y’,’m’,’B’,’b’,’d’,’H’,’M’,’S’ and ‘f’ are supported for all calendars and dates. If the date is valid in the python ‘proleptic_gregorian’ calendar, then python’s datetime.strptime is used. For a complete list of formatting directives supported in python’s datetime.strptime, 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.

toordinal(self, fractional=False)

Return (integer) julian day ordinal.

Day 0 starts at noon January 1 of the year -4713 for the julian, gregorian and standard calendars (year -4712 if year zero allowed).

Day 0 starts at noon on November 24 of the year -4714 for the proleptic gregorian calendar (year -4713 if year zero allowed).

Day 0 starts at noon on January 1 of the year zero is for the 360_day, 365_day, 366_day, all_leap and noleap calendars.

If fractional=True, fractional part of day is included (default False).

cftime.is_leap_year(year, calendar, has_year_zero=None)

returns True if specified year in specified calendar is a leap year. Optional kwarg has_year_zero controls whether astronomical year numbering is used and the year zero exists. If not specified, calendar-specific default is assumed.

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

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 and common_years since is allowed only for the 365_day calendar.

calendar: describes the calendar used in the time calculations. All the values currently defined in the CF metadata convention are supported. 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.

has_year_zero: if set to True, astronomical year numbering is used and the year zero exists. If set to False for real-world calendars, then historical year numbering is used and the year 1 is preceded by year -1 and no year zero exists. The defaults are set to conform with CF version 1.9 conventions (False for ‘julian’, ‘gregorian’/’standard’, True for ‘proleptic_gregorian’ (ISO 8601) and True for the idealized calendars ‘noleap’/’365_day’, ‘360_day’, 366_day’/’all_leap’) The defaults can only be over-ridden for the real-world calendars, for the the idealized calendars the year zero always exists and the has_year_zero kwarg is ignored. This kwarg is not needed to define calendar systems allowed by CF (the calendar-specific defaults do this).

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.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 units attribute. The entries are assumed to be stored in increasing order.

calendar: Describes the calendar used in the time calculation. 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 times given. before and after will return the indices corresponding to the times just before or just after the given times if an exact match cannot be found. nearest will return the indices that correspond to the closest times.

cftime.to_tuple(dt)

Turn a datetime.datetime instance into a tuple of integers. Elements go in the order of decreasing significance, making it easy to compare datetime instances. Parts of the state that don’t affect ordering are omitted. Compare to datetime.timetuple().