Python timedeltaの使い方

Python
データ型

最終更新日: 2025/11/28

この記事のポイント

この記事では、時間の差分を扱えるPythonのtimedeltaについて紹介します。初心者の方でも理解できるよう、基本概念から実践的な活用方法までわかりやすく解説しました。

本記事から得られるポイントは、次の通りです。

Pythonのtimedeltaによる時間間隔の計算と操作機能
基本構文とコード例を使った具体的な実装方法
実際の開発現場で活用できる8つのサンプルコード集

これらのポイントを押さえることで、日時処理における効率的なプログラミングが可能になります。

dateとは？

Pythonのtimedeltaはdatetimeモジュールに含まれるクラスの一つで、時間の間隔や差を表現できるのが特徴です。日、秒、マイクロ秒の単位で時間の長さを扱うことができ、日付や時刻の計算において重要な役割を果たします。

たとえば、ある日付から3日後の日付を求めたり、2つの時刻の差を計算したりする際にとても実用的です。また、timedeltaオブジェクトは datetimeオブジェクトとの加算や減算が可能で、プログラム内で時間に関するさまざまな操作を直感的に行うことができます。

【関連】
Pythonをもっと詳しく学ぶならpaizaラーニング

基本構文

Pythonのtimedeltaの使用には、datetimeモジュールからtimedeltaクラスのインポートが必要です。基本的な使い方としては、日数、秒数、マイクロ秒などのパラメータを指定してtimedeltaオブジェクトを作成します。

また、datetimeオブジェクトとtimedeltaの加算・減算処理を応用すれば、未来や過去の日時計算も簡単です。以下に示すコード例では、timedeltaの基本的な作成方法と、datetimeオブジェクトとの組み合わせによる日時計算の実装例を紹介します。

# 基本的なtimedeltaオブジェクトの作成 from datetime import datetime, timedelta def calculate_and_display_time() -> None: delta_interval = timedelta(days=7, hours=3, minutes=30) print(f"時間間隔: {delta_interval}") # 現在の日時を取得 now_date = datetime.now() # 5日後の日時を計算 days_to_add = 5 future_date = now_date + timedelta(days=days_to_add) # 結果の出力 print(f"{days_to_add}日後: {future_date.strftime('%Y-%m-%d %H:%M:%S')}") if __name__ == "__main__": calculate_and_display_time()

出力結果（例）

時間間隔: 7 days, 3:30:00
5日後: 2025-11-20 14:15:05

※このページ内のコードの出力結果の一部で、実行した時刻により変動するものがあります。また、日時はUTC形式で計算されるため、日本時間での計算結果と異なる場合があります

実用例

ここからは、Pythonのtimedeltaの具体的な活用方法を8つのサンプルコードで詳しく解説していきます。

各例では、実際の開発現場でよく遭遇する場面を想定し、timedeltaの特徴を活かした効率的なコード記述方法を紹介しました。日時の加算減算から時間差の計算、定期的なタスクの実装まで、幅広い用途でのtimedeltaの使い方を学ぶことができます。すべてのサンプルコードは実行可能な形で記載していますので、実際にコードを動かしながら理解を深めていきましょう。

日付の加算と減算による未来・過去の日付計算

特定の日付から一定期間前後の日付を求める処理は、スケジュール管理やデータ分析でよく使用されます。timedeltaを使用することで直感的な日付計算が実現できます。

# 日付の加算と減算サンプル from datetime import datetime, timedelta BASE_DATE = datetime(2024, 6, 15) DAYS_FUTURE = 30 DAYS_PAST = 60 def calculate_past_and_future_dates() -> None: # 30日後と60日前の日付を計算 future_date = BASE_DATE + timedelta(days=DAYS_FUTURE) past_date = BASE_DATE - timedelta(days=DAYS_PAST) print(f"基準日: {BASE_DATE.strftime('%Y-%m-%d')}") print(f"{DAYS_FUTURE}日後: {future_date.strftime('%Y-%m-%d')}") print(f"{DAYS_PAST}日前: {past_date.strftime('%Y-%m-%d')}") if __name__ == "__main__": calculate_past_and_future_dates()

出力結果

基準日: 2024-06-15
30日後: 2024-07-15
60日前: 2024-04-16

ウサギの誕生日まで残り日数計算

イベントや記念日までの残り日数を計算するアプリケーションでよく使用される処理です。現在日時と目標日時の差を求めることで実装できます。

# 指定日までの残り日数を計算 from datetime import datetime, timedelta RABBIT_BIRTHDAY_MONTH = 12 RABBIT_BIRTHDAY_DAY = 31 def calculate_remaining_days() -> None: current_date = datetime.now() # 今年の誕生日を作成 rabbit_birthday = datetime( current_date.year, RABBIT_BIRTHDAY_MONTH, RABBIT_BIRTHDAY_DAY ) # 今年の誕生日が過ぎていたら、来年にずらす if rabbit_birthday < current_date: rabbit_birthday = datetime( current_date.year + 1, RABBIT_BIRTHDAY_MONTH, RABBIT_BIRTHDAY_DAY ) # 残り時間と残り日数を計算 remaining_time = rabbit_birthday - current_date remaining_days = remaining_time.days print(f"今日: {current_date.strftime('%Y-%m-%d')}") print(f"ウサギの誕生日: {rabbit_birthday.strftime('%Y-%m-%d')}") print(f"残り日数: {remaining_days}日") if __name__ == "__main__": calculate_remaining_days()

出力結果（例）

今日: 2025-11-15
ウサギの誕生日: 2025-12-31
残り日数: 45日

営業時間の計算とネコの勤務時間管理

業務システムにおける勤務時間の計算や営業時間の管理にtimedeltaを活用した例です。時間単位での計算が簡潔に記述できます。

# 業務システムでの勤務時間や営業時間の管理例 from datetime import datetime, timedelta # ネコの出退勤時間を設定 START_TIME = datetime(2024, 1, 15, 9, 0, 0) END_TIME = datetime(2024, 1, 15, 17, 30, 0) def calculate_work_duration() -> None: # 勤務時間を計算 work_duration = END_TIME - START_TIME # 勤務時間を時間単位に変換 work_hours = work_duration.total_seconds() / 3600 print(f"出勤時刻: {START_TIME.strftime('%H:%M')}") print(f"退勤時刻: {END_TIME.strftime('%H:%M')}") print(f"ネコの勤務時間: {work_hours}時間") if __name__ == "__main__": calculate_work_duration()

出力結果

出勤時刻: 09:00
退勤時刻: 17:30
ネコの勤務時間: 8.5時間

イヌの散歩時間間隔チェック機能

定期的なタスクの実行間隔をチェックする処理です。前回の実行時刻と現在時刻の差を計算して、次の実行タイミングを判定します。

from datetime import datetime, timedelta # イヌの前回散歩時刻と散歩間隔を設定 LAST_WALK_TIME = datetime(2024, 1, 15, 8, 0, 0) WALK_INTERVAL = timedelta(hours=6) # 現在時刻 (2024/1/15 13:30) CURRENT_TIME = datetime( 2024, 1, 15, 13, 30, 0 ) def calculate_next_walk_time() -> None: # 次回散歩時刻と残り時間を計算 next_walk = LAST_WALK_TIME + WALK_INTERVAL time_left = next_walk - CURRENT_TIME print(f"前回散歩: {LAST_WALK_TIME.strftime('%H:%M')}") print(f"現在時刻: {CURRENT_TIME.strftime('%H:%M')}") print(f"次回散歩まで: {time_left}") if __name__ == "__main__": calculate_next_walk_time()

出力結果

前回散歩: 08:00
現在時刻: 13:30
次回散歩まで: 0:30:00

パンダの餌やり週間スケジュール生成

反復的なスケジュールを生成する処理です。基準日から一定間隔で複数の日付を自動生成する際に活用できます。

# 反復的なスケジュールの生成管理の例 from datetime import datetime, timedelta # パンダの餌やり開始日と間隔を設定 START_DATE = datetime(2024, 1, 15) FEEDING_INTERVAL = timedelta(days=2) SCHEDULE_COUNT = 4 def generate_feeding_schedule() -> None: # 1週間分の餌やりスケジュールを生成 schedule_list = [] # SCHEDULE_COUNT分の日付をループで計算し、リストに追加 for i in range(SCHEDULE_COUNT): feeding_date = START_DATE + (FEEDING_INTERVAL * i) schedule_list.append(feeding_date) print("パンダの餌やりスケジュール:") for date_item in schedule_list: print(f" {date_item.strftime('%Y-%m-%d')}") if __name__ == "__main__": generate_feeding_schedule()

出力結果

パンダの餌やりスケジュール:
  2024-01-15
  2024-01-17
  2024-01-19
  2024-01-21

サルの年齢計算機能

生年月日から現在の年齢を計算する処理です。timedeltaを使用して日単位での正確な年齢計算を実装できます。

# 生年月日と指定年月日から年齢を計算する例 from datetime import datetime, timedelta # サルの生年月日を設定 BIRTH_DATE = datetime(2020, 3, 10) CURRENT_DATE = datetime(2024, 1, 15) DAYS_PER_YEAR = 365.25 def calculate_age() -> None: # 年齢を日数で計算 age_delta = CURRENT_DATE - BIRTH_DATE age_days = age_delta.days age_years = age_days / DAYS_PER_YEAR print(f"サルの生年月日: {BIRTH_DATE.strftime('%Y-%m-%d')}") print(f"現在の日付: {CURRENT_DATE.strftime('%Y-%m-%d')}") print(f"サルの年齢: {age_years:.1f}歳 ({age_days}日)") if __name__ == "__main__": calculate_age()

出力結果

サルの生年月日: 2020-03-10
現在の日付: 2024-01-15
サルの年齢: 3.8歳 (1406日)

クジラの移動時間予測システム

移動や配送の所要時間を計算するシステムでの活用例です。出発時刻と所要時間から到着予定時刻を算出します。

# datetimeを用いた時間計算の例 from datetime import datetime, timedelta # クジラの移動開始時刻と所要時間を設定 DEPARTURE_TIME = datetime(2024, 1, 15, 10, 30, 0) TRAVEL_DURATION = timedelta(hours=2, minutes=45) def calculate_arrival_time() -> None: # 到着予定時刻を計算 arrival_time = DEPARTURE_TIME + TRAVEL_DURATION total_minutes = TRAVEL_DURATION.total_seconds() / 60 print(f"クジラの出発時刻: {DEPARTURE_TIME.strftime('%H:%M')}") print(f"移動時間: {total_minutes:.0f}分") print(f"到着予定時刻: {arrival_time.strftime('%H:%M')}") if __name__ == "__main__": calculate_arrival_time()

出力結果

クジラの出発時刻: 10:30
移動時間: 165分
到着予定時刻: 13:15

ペンギンの作業効率分析ツール

作業時間の分析や効率測定を行うツールでの活用例です。複数の作業時間を合計して全体の作業効率を計算します。

# 作業時間の合計や平均を出すサンプル from datetime import datetime, timedelta # ペンギンの各作業時間を設定 TASK_ONE_DURATION = timedelta(hours=1, minutes=30) TASK_TWO_DURATION = timedelta(hours=2, minutes=15) TASK_THREE_DURATION = timedelta(minutes=45) NUMBER_OF_TASKS = 3 def calculate_task_metrics() -> None: # 総作業時間と平均作業時間を計算 total_time = ( TASK_ONE_DURATION + TASK_TWO_DURATION + TASK_THREE_DURATION ) total_hours = total_time.total_seconds() / 3600 average_hours = total_hours / NUMBER_OF_TASKS # 結果の出力 print(f"作業1: {TASK_ONE_DURATION}") print(f"作業2: {TASK_TWO_DURATION}") print(f"作業3: {TASK_THREE_DURATION}") print(f"ペンギンの平均作業時間: {average_hours:.2f}時間") print(f"ペンギンの総作業時間: {total_hours:.2f}時間") if __name__ == "__main__": calculate_task_metrics()

出力結果

作業1: 1:30:00
作業2: 2:15:00
作業3: 0:45:00
ペンギンの平均作業時間: 1.50時間
ペンギンの総作業時間: 4.50時間

まとめ

Pythonのtimedeltaは、日時処理において欠かせない重要な機能であり、時間間隔の計算や日付の操作を直感的かつ効率的に行うことができます。基本的な構文から実用的な応用例まで、さまざまな場面でその威力を発揮することが理解できたでしょう。プログラミングにおける時間処理の複雑さを大幅に軽減し、可読性の高いコードを記述することが可能になります。

timedeltaの活躍する場面