5.1.2 timedelta オブジェクト

5.1.2 `timedelta` オブジェクト

timedelta オブジェクトは経過時間、すなわち二つの日付や時刻間の差を表します。

クラス timedelta( [days[, seconds[, microseconds[, milliseconds[, minutes[, hours[, weeks]]]]]]])

全ての引数がオプションで、デフォルト値は0です。引数は整数、長整数、浮動小数点数にすることができ、正でも負でもかまいません。

days、seconds および microseconds のみが内部に記憶されます。引数は以下のようにして変換されます:

1 ミリ秒は 1000 マイクロ秒に変換されます。
1 分は 60 秒に変換されます。
1 時間は 3600 秒に変換されます。
1 週間は 7 日に変換されます。

その後、日、秒、マイクロ秒は値が一意に表されるように、

0 <= microseconds < 1000000
0 <= seconds < 3600*24 (一日中の秒数)
-999999999 <= days <= 999999999

で正規化されます。

引数のいずれかが浮動小数点であり、小数のマイクロ秒が存在する場合、小数のマイクロ秒は全ての引数から一度取り置かれ、それらの和は最も近いマイクロ秒に丸められます。浮動小数点の引数がない場合、値の変換と正規化の過程は厳密な (失われる情報がない) ものとなります。

日の値を正規化した結果、指定された範囲の外側になった場合には、 OverflowError が送出されます。

負の値を正規化すると、一見混乱するような値になります。例えば、

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

クラス属性を以下に示します:

min: 最小の値を表す timedelta オブジェクトで、 timedelta(-999999999) です。

max: 最大の値を表す timedelta オブジェクトで、 timedelta(days=999999999, hours=23, minutes=59, seconds=59, microseconds=999999) です。

resolution: timedelta オブジェクトが等しくならない最小の時間差で、timedelta(microseconds=1) です。

正規化のために、timedelta.max >-timedelta.min となるので注意してください。-timedelta.max は timedelta オブジェクトとして表現することができません。

以下に (読み出し専用の) インスタンス属性を示します:

属性	値
`days`	両端値を含む -999999999 から 999999999 の間
`seconds`	両端値を含む 0 から 86399 の間
`microseconds`	両端値を含む 0 から 999999 の間

サポートされている操作を以下に示します:

演算	結果
`t1 = t2 + t3`	`t2` と `t3` を加算します。演算後、 `t1`-`t2` == `t3` および `t1`-`t3` == `t2` は真になります。 (1)
`t1 = t2 - t3`	`t2` と `t3` の差分です。演算後、 `t1` == `t2` - `t3` および `t2` == `t1` + `t3` は真になります。 (1)
`t1 = t2 * i or t1 = i * t2`	整数や長整数による乗算です。演算後、 `t1` // i == `t2` は `i != 0` であれば真となります。
	一般的に、 `t1` * i == `t1` * (i-1) + `t1` は真となります。(1)
`t1 = t2 // i`	端数を切り捨てて除算され、剰余 (がある場合) は捨てられます。(3)
`+t1`	同じ値を持つ`timedelta` オブジェクトを返します。(2)
`-t1`	`timedelta`(-`t1.days`, -`t1.seconds`, -`t1.microseconds`)、および `t1`* -1 と同じです。 (1)(4)
`abs(t)`	`t.days >= 0` のときには +`t` 、`t.days < 0` のときには -`t` となります。(2)

注釈:

(1): この操作は厳密ですが、オーバフローするかもしれません。
(2): この操作は厳密であり、オーバフローしないはずです。
(3): 0 による除算は ZeroDivisionError を送出します。
(4): -timedelta.max は timedelta オブジェクトで表現することができません。

上に列挙した操作に加えて、timedelta オブジェクトは date および datetime オブジェクトとの間で加減算をサポートしています (下を参照してください)。

timedelta オブジェクト間の比較はサポートされており、より小さい経過時間を表す timedelta オブジェクトがより小さい timedelta と見なされます。型混合の比較がデフォルトのオブジェクトアドレス比較となってしまうのを抑止するために、timedelta オブジェクトと異なる型のオブジェクトが比較されると、比較演算子が == または != でないかぎり TypeError が送出されます。後者の場合、それぞれ False または True を返します。

timedelta オブジェクトはハッシュ可能 (辞書のキーとして利用可能) であり、効率的な pickle 化をサポートします、また、ブール演算コンテキストでは、 timedelta オブジェクトは timedelta(0) に等しくない場合かつそのときに限り真となります。

ご意見やご指摘をお寄せになりたい方は、 このドキュメントについて... をご覧ください。