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 False for real-world calendars and True for idealized calendars. 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)

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.

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 False for real-world calendars and True for idealized calendars. 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 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 using the same calendar.

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 False for real-world calendars and True for idealized calendars. 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')
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.

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 allowd).

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.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.

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 False for real-world calendars and True for idealized calendars. 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.