6.9.2 timedelta Objects

##
6.9.2 `timedelta` Objects

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

class `timedelta`( | days=0, seconds=0, microseconds=0, milliseconds=0, minutes=0, hours=0, weeks=0)

  All arguments are optional. 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):

Attribute | Value
--- | ---
`days` | Between -999999999 and 999999999 inclusive
`seconds` | Between 0 and 86399 inclusive
`microseconds` | Between 0 and 999999 inclusive

Supported operations:

Operation | Result
--- | ---
`t1 = t2 + t3` | Sum of t2 and t3. Afterwards t1-t2 == t3 and t1-t3 == t2 are true. (1)
`t1 = t2 - t3` | Difference of t2 and t3. Afterwards t1 == t2 - t3 and t2 == t1 + t3 are true. (1)
`t1 = t2 * i or t1 = i * t2` | Delta multiplied by an integer or long. Afterwards t1 // i == t2 is true, provided `i != 0`.
`` | In general, t1 * i == t1 * (i-1) + t1 is true. (1)
`t1 = t2 // i` | The floor is computed and the remainder (if any) is thrown away. (3)
`+t1` | Returns a `timedelta` object with the same value. (2)
`-t1` | equivalent to `timedelta`(-t1.days, -t1.seconds, -t1.microseconds), and to t1* -1. (1)(4)
`abs(t)` | equivalent to +t when `t.days >= 0`, and to -t when `t.days < 0`. (2)

Notes:

(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)`.