今回は、Pythonのtimedeltaで経過日時や時間を算出する方法についてご紹介します。
timedeltaオブジェクトとは
timedeltaは、Pythonのdatetimeモジュールで日付や時間の差分を表すためのクラスです。
主に日数（days）、秒（seconds）、マイクロ秒（microseconds）を基本単位として扱います。
同モジュールのdatetimeオブジェクト同士の差分を取得すると、このtimedeltaオブジェクトが生成されます。
また、ある日時に対して期間を加算・減算する際に用いることも可能です。
基本的な使い方
2つの日時の差を計算
2つの日時オブジェクトの差をとると、timedeltaオブジェクトが生成されます。
以下の例では、2025年2月15日12時0分0秒から翌日の15時30分までの経過時間を計算しています。
|
1 2 3 4 5 6 7 8 9 10 11 12 |
from datetime import datetime # 開始時刻と終了時刻の定義 start_time = datetime(2025, 2, 15, 12, 0, 0) end_time = datetime(2025, 2, 16, 15, 30, 0) # 差分（timedeltaオブジェクト）の計算 elapsed = end_time - start_time print("経過時間:", elapsed) print("日数:", elapsed.days) print("秒数:", elapsed.seconds) |
経過時間: 1 day, 3:30:00
日数: 1
秒数: 12600
このように、daysやsecondsといった属性から、日数や秒数を直接取り出すことができます。
日時の加算・減算
timedeltaを使えば、特定の日時に任意の日数や時間を加算・減算することができます。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
from datetime import datetime, timedelta # 現在の日時を取得 now = datetime.now() # 2日と3時間の時間差を定義 delta = timedelta(days=2, hours=3) # 現在日時に加算・減算する future_time = now + delta past_time = now - delta print("現在時刻:", now) print("未来の時刻:", future_time) print("過去の時刻:", past_time) |
現在時刻: 2025-02-15 12:00:00.000000
未来の時刻: 2025-02-17 15:00:00.000000
過去の時刻: 2025-02-13 09:00:00.000000
このように、特定日時から任意の期間を加算することで未来の日時を、減算することで過去の日時を取得することができます。
実行時間の計測
timedeltaオブジェクトは、処理の開始時刻と終了時刻をとることで、実行にかかった時間を簡単に測定できます。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
import time from datetime import datetime # 処理開始時刻の取得 start = datetime.now() # 何らかの処理（ここでは2秒待機） time.sleep(2) # 処理終了時刻の取得 end = datetime.now() # 経過時間を計算 elapsed = end - start print("実行時間:", elapsed) |
実行時間: 0:00:02.000123
簡易的なパフォーマンス計測や、特定タスクの実行時間をログに記録する場面で役立ちます。
よくあるエラーや注意点
timedeltaオブジェクトを扱う上で、以下の点に注意が必要です。
- タイムゾーンの混在
aware（タイムゾーン情報あり）とnaive（タイムゾーン情報なし）のdatetimeオブジェクト同士で差分をとるとエラーになる場合があります。
使用するdatetimeオブジェクトを統一し、必要に応じてpytzやzoneinfoなどを用いてタイムゾーンを扱うようにしてください。
- 内部単位
timedeltaは日数や秒、マイクロ秒で内部的に計算を行います。
時間や分など他の単位は換算される点を把握しておくと、計算結果の解釈で混乱しにくくなります。
- サマータイム（DST）の影響
サマータイムや地域の祝日などにより、時間がずれるケースがあります。
正確な日時計算が必要な場合は、タイムゾーン情報を含めて計算することが推奨されます。
- 型の不一致
datetimeオブジェクトと文字列（str）を直接加算するなど、型が一致しない演算を行うとエラーになります。
エラー内容が「unsupported operand type(s) for +: ‘datetime.datetime’ and ‘str’」などの場合は、日時を文字列ではなくdatetimeオブジェクトとして正しく扱う必要があります。
まとめ
timedeltaを使うことで、日付や時間の差分を柔軟に計算・操作できます。
加算や減算のほか、実行時間の測定など幅広い場面で利用可能です。
タイムゾーンや内部単位の扱いに注意しながら、正確な日時処理に活用してみてください。
