6.10.2 timedelta Objects

6.10.2 timedelta Objects

A timedelta object represents a duration, the difference between two dates or times.

class timedelta(

[days[, seconds[, microseconds[, milliseconds[, minutes[, hours[, weeks]]]]]]])

All arguments are optional and default to 0. Arguments may be ints, longs, or floats, and may be positive or negative.

Only days, seconds and microseconds are stored internally. Arguments are converted to those units:

• A millisecond is converted to 1000 microseconds.
• A minute is converted to 60 seconds.
• An hour is converted to 3600 seconds.
• A week is converted to 7 days.

and days, seconds and microseconds are then normalized so that the representation is unique, with

• 0 <= microseconds < 1000000
• 0 <= seconds < 3600*24 (the number of seconds in one day)
• -999999999 <= days <= 999999999

If any argument is a float and there are fractional microseconds, the fractional microseconds left over from all arguments are combined and their sum is rounded to the nearest microsecond. If no argument is a float, the conversion and normalization processes are exact (no information is lost).

If the normalized value of days lies outside the indicated range, OverflowError is raised.

Note that normalization of negative values may be surprising at first. For example,

>>> d = timedelta(microseconds=-1)
>>> (d.days, d.seconds, d.microseconds)
(-1, 86399, 999999)

Class attributes are:

min

The most negative timedelta object, timedelta(-999999999).

max

The most positive timedelta object, timedelta(days=999999999, hours=23, minutes=59, seconds=59, microseconds=999999).

resolution

The smallest possible difference between non-equal timedelta objects, timedelta(microseconds=1).

Note that, because of normalization, timedelta.max > -timedelta.min. -timedelta.max is not representable as a timedelta object.

Instance attributes (read-only):

Supported operations:

(1)

This is exact, but may overflow.

(2)

This is exact, and cannot overflow.

(3)

Division by 0 raises ZeroDivisionError.

(4)

-timedelta.max is not representable as a timedelta object.

In addition to the operations listed above timedelta objects support certain additions and subtractions with date and datetime objects (see below).

Comparisons of timedelta objects are supported with the timedelta object representing the smaller duration considered to be the smaller timedelta. In order to stop mixed-type comparisons from falling back to the default comparison by object address, when a timedelta object is compared to an object of a different type, TypeError is raised unless the comparison is == or !=. The latter cases return False or True, respectively.

timedelta objects are hashable (usable as dictionary keys), support efficient pickling, and in Boolean contexts, a timedelta object is considered to be true if and only if it isn't equal to timedelta(0).

---

Python Library Reference

Previous: 6.10.1 Available Types Up: 6.10 datetime Next: 6.10.3 date Objects

---

Release 2.4.4c1, documentation updated on 11 October 2006.