cf.TimeDuration¶

class
cf.
TimeDuration
(duration, units=None, month=1, day=1, hour=0, minute=0, second=0)[source]¶ Bases:
object
A duration of time.
The duration of time is a number of either calendar years, calendar months, days, hours, minutes or seconds.
A calendar year (or month) is an arbitrary year (or month) in an arbitrary calendar. A calendar is as part of the time duration, but will be taken from the context in which the time duration instance is being used. For example, a calendar may be specified when creating time intervals (see below for examples).
A default offset is specified that may be used by some applications to temporally position the time duration. For example, setting
cf.TimeDuration(1, 'calendar_month', day=16, hour=12)
will define a duration of one calendar month which, by default, starts at 12:00 on the 16th of the month. Note that the offsetChanging the units
The time duration’s units may be changed in place by assigning equivalent units to the
Units
attribute:>>> t = cf.TimeDuration(1, 'day') >>> t <CF TimeDuration: P1D (YMD 00:00:00)> >>> t.Units = 's' >>> t <CF TimeDuration: PT86400.0S (YMD 00:00:00)> >>> t.Units = cf.Units('minutes') >>> t <CF TimeDuration: PT1440.0M (YMD 00:00:00)> >>> t.Units = 'calendar_months' ValueError: Can't set units (currently <Units: minutes>) to nonequivalent units <Units: calendar_months>
Creating time intervals
A time interval of exactly the time duration, starting or ending at a particular datetime, may be produced with the
interval
method. If elements of the start or end datetime are not specified, then default values are taken from theyear
,month
,day
,hour
,minute
, andsecond
attributes of the time duration instance:>>> t = cf.TimeDuration(6, 'calendar_months') >>> t <CF TimeDuration: P6M (YM01 00:00:00)> >>> t.interval(cf.dt(1999, 12)) (cftime.DatetimeGregorian(19991201 00:00:00), cftime.DatetimeGregorian(20000601 00:00:00)) >>> t = cf.TimeDuration(5, 'days', hour=6) >>> t <CF TimeDuration: P5D (YMD 06:00:00)> >>> t.interval(cf.dt(2004, 3, 2), end=True) (cftime.DatetimeGregorian(20040226 00:00:00), cftime.DatetimeGregorian(20040302 00:00:00)) >>> t.interval(cf.dt(2004, 3, 2, calendar='noleap'), end=True) (cftime.DatetimeNoLeap(20040225 00:00:00), cftime.DatetimeNoLeap(20040302 00:00:00)) >>> t.interval(cf.dt(2004, 3, 2, calendar='360_day'), end=True) (cftime.Datetime360Day(20040227 00:00:00), cftime.Datetime360Day(20040302 00:00:00)) >>> t.interval(cf.dt(2004, 3, 2, calendar='360_day'), end=True, ... iso='start and duration') '20040227 00:00:00/P5D'
Comparison operations
Comparison operations are defined for
cf.TimeDuration
objects,cf.Data
objects,numpy
arrays and numbers:>>> cf.TimeDuration(2, 'calendar_years') > cf.TimeDuration( ... 1, 'calendar_years') True >>> cf.TimeDuration(2, 'calendar_years') < cf.TimeDuration( ... 25, 'calendar_months') True >>> cf.TimeDuration(2, 'hours') <= cf.TimeDuration(1, 'days') True >>> cf.TimeDuration(2, 'hours') == cf.TimeDuration(1/12.0, 'days') True >>> cf.TimeDuration(2, 'days') == cf.TimeDuration(48, 'hours') True
>>> cf.TimeDuration(2, 'hours') <= 2 True >>> 30.5 != cf.TimeDuration(2, 'days') True
>>> cf.TimeDuration(2, 'calendar_years') > numpy.array(1.5) True >>> type(cf.TimeDuration(2, 'calendar_years') > numpy.array(1.5)) numpy.bool_ >>> cf.TimeDuration(2, 'calendar_years') > numpy.array([1.5]) array([ True]) >>> numpy.array([[1, 12]]) > cf.TimeDuration(2, 'calendar_months') array([[False, True]])
>>> cf.TimeDuration(2, 'days') == cf.Data(2) <CF Data(): True> >>> cf.TimeDuration(2, 'days') == cf.Data([2.], 'days') <CF Data(1): [True]> >>> cf.Data([[60]], 'seconds') < cf.TimeDuration(2, 'days') <CF Data(1, 1): [[True]]> >>> cf.Data([1, 12], 'calendar_months') < cf.TimeDuration( ... 6, 'calendar_months') <CF Data(2): [True, False]>
Arithmetic operations
Arithmetic operations are defined for
cf.TimeDuration
objects, datetimelike objects (such ascf.Datetime
,datetime.datetime
, etc.),cf.Data
objects,numpy
arrays and numbers:>>> cf.TimeDuration(64, 'days') + cf.TimeDuration(28, 'days') <CF TimeDuration: P92D (YMD 00:00:00)> >>> cf.TimeDuration(64, 'days') + cf.TimeDuration(12, 'hours') <CF TimeDuration: P65.0D (YMD 00:00:00)> >>> cf.TimeDuration(64, 'days') + cf.TimeDuration(24, 'hours') <CF TimeDuration: P64.5D (YMD 00:00:00)> >>> cf.TimeDuration(64, 'calendar_years') + cf.TimeDuration( ... 21, 'calendar_months') <CF TimeDuration: P65.75Y (Y0101 00:00:00)>
>>> cf.TimeDuration(30, 'days') + 2 <CF TimeDuration: P32D (YMD 00:00:00)> >>> 4.5 + cf.TimeDuration(30, 'days') <CF TimeDuration: P34.5D (YMD 00:00:00)> >>> cf.TimeDuration(64, 'calendar_years')  2.5 <CF TimeDuration: P61.5Y (Y0101 00:00:00)>
>>> cf.TimeDuration(36, 'hours') / numpy.array(8) <CF TimeDuration: 4.5 hours (from YMD h:00:00)> >>> cf.TimeDuration(36, 'hours') / numpy.array(8.0) <CF TimeDuration: 4.5 hours (from YMD h:00:00)> >>> cf.TimeDuration(36, 'hours') // numpy.array(8.0) <CF TimeDuration: 4.0 hours (from YMD h:00:00)> >>> cf.TimeDuration(36, 'calendar_months') * cf.Data([[2.25]]) <CF TimeDuration: 81.0 calendar_months (from YM01 00:00:00)> >>> cf.TimeDuration(36, 'calendar_months') // cf.Data([0.825]) <CF TimeDuration: P43.0M (Y0101 00:00:00)> >>> cf.TimeDuration(36, 'calendar_months') % 10 <CF TimeDuration: P6M (Y0101 00:00:00)> >>> cf.TimeDuration(36, 'calendar_months') % cf.Data(1, 'calendar_year') <CF TimeDuration: P0.0M (Y0101 00:00:00)> >>> cf.TimeDuration(36, 'calendar_months') % cf.Data(2, 'calendar_year') <CF TimeDuration: P12.0M (Y0101 00:00:00)>
The in place operators (
+=
,//=
, etc.) are supported in a similar manner.Attributes
Attribute
Description
duration
The length of the time duration in a
cf.Data
object with units.year
The default year for time interval creation.
month
The default month for time interval creation.
day
The default day for time interval creation.
hour
The default hour for time interval creation.
minute
The default minute for time interval creation.
second
The default second for time interval creation.
Constructors
For convenience, the following functions may also be used to create time duration objects:
Function
Description
Create a time duration of calendar years.
Create a time duration of calendar months.
Create a time duration of days.
Create a time duration of hours.
Create a time duration of minutes.
Create a time duration of seconds.
New in version 1.0.
Initialisation
 Parameters
 duration: datalike
The length of the time duration.
A datalike object is any object containing arraylike or scalar data which could be used to create a
cf.Data
object. units:
str
orcf.Units
, optional The units of the time duration. Required if, and only if, duration is not a
cf.Data
object which already contains the units. Units must be one of calendar years, calendar months, days, hours, minutes or seconds. Parameter example:
units='calendar_months'
 Parameter example:
units='days'
 Parameter example:
units=cf.Units('calendar_years')
 month, day, hour, minute, second:
int
orNone
, optional The offset used when creating, with the
bounds
method, a time interval containing a given datetime.Note
The offset element month is ignored unless the time duration is at least 1 calendar year.
The offset element day is ignored unless the time duration is at least 1 calendar month.
The offset element hour is ignored unless the time duration is at least 1 day
The offset element minute is ignored unless the time duration is at least 1 hour.
The offset element second is ignored unless the time duration is at least 1 minute
 Parameter example:
>>> cf.TimeDuration(1, 'calendar_month').bounds( ... cf.dt('200018')) (cftime.DatetimeGregorian(20000101 00:00:00), cftime.DatetimeGregorian(20000201 00:00:00)) >>> cf.TimeDuration(1, 'calendar_month', day=15).bounds( ... cf.dt('200018')) (cftime.DatetimeGregorian(19991215 00:00:00), cftime.DatetimeGregorian(20000115 00:00:00)) >>> cf.TimeDuration( ... 1, 'calendar_month', month=4, day=30).bounds( ... cf.dt('200018')) (cftime.DatetimeGregorian(19991230 00:00:00), cftime.DatetimeGregorian(20000130 00:00:00))
Examples
>>> t = cf.TimeDuration(cf.Data(3 , 'calendar_years')) >>> t = cf.TimeDuration(cf.Data(12 , 'hours')) >>> t = cf.TimeDuration(18 , 'calendar_months') >>> t = cf.TimeDuration(30 , 'days') >>> t = cf.TimeDuration(1 , 'day', hour=6)
Attributes¶
The units of the time duration. 

True if the time duration is a whole number. 

Return the time duration as an ISO 8601like time duration string. 
Methods¶
Return a time interval containing a datetime. 

Return a deep copy. 

The number of days in a specific month in a specific year in a specific calendar. 

True if two time durations are equal. 

True if two time durations are logically equivalent. 

Inspect the attributes. 

Return a time interval of exactly the time duration. 

Return True if an integer multiple of the time duration is equal to one day. 
Special¶
Methods
Used if copy.deepcopy is called. 

Called by the 

“Called by the 

The unary arithmetic operation 

Truth value testing and the builtin operation 

The unary arithmetic operation 

Called to implement the builtin function 

The rich comparison operator 

The rich comparison operator 

The rich comparison operator 

The rich comparison operator 

The rich comparison operator 

The rich comparison operator 

The binary arithmetic operation 

The binary arithmetic operation 

The binary arithmetic operation 

The binary arithmetic operation 

The binary arithmetic operation 

The binary arithmetic operation 

The augmented arithmetic assignment 

The augmented arithmetic assignment 

The augmented arithmetic assignment 

The augmented arithmetic assignment 

The augmented arithmetic assignment 

The augmented arithmetic assignment 

The augmented arithmetic assignment 

The binary arithmetic operation 

The binary arithmetic operation 

The binary arithmetic operation 

The binary arithmetic operation 

Returns a 

Return a hashable value fully representative of the object. 

Returns a new reference to the 