datetime.timedelta()

from datetime import datetime, timedelta

# 期間オブジェクトを生成する
delta = timedelta(days=日数, hours=時間, minutes=分, seconds=秒, weeks=週)

# 日時に期間を加算する
未来 = 日時 + delta

# 日時から期間を減算する
過去 = 日時 - delta

# 2つの日時の差を求める（結果は timedelta）
差 = 日時A - 日時B

datetime_timedelta.py

from datetime import datetime, timedelta

# 基準日時を設定する
now = datetime(2025, 4, 15, 7, 30, 0)

# 基準日時から7日後の日時を求める
one_week_later = now + timedelta(weeks=1)
print(one_week_later.strftime('%Y-%m-%d'))  # 1週間後の日付が出力される

# 30日前の日時を求める
thirty_days_ago = now - timedelta(days=30)
print(thirty_days_ago.strftime('%Y-%m-%d'))  # 30日前の日付が出力される

# 複数の単位を組み合わせて計算する
deadline = now + timedelta(days=3, hours=5, minutes=30)
print(deadline.strftime('%Y年%m月%d日 %H:%M'))  # 締め切り日時が出力される

# 2つの日時の差を求める
birthday = datetime(2000, 1, 1)
diff = now - birthday
print(f'{diff.days}日が経過しました。')  # 経過日数が出力される

# total_seconds() で総秒数を取得する
delta = timedelta(hours=2, minutes=30)
print(delta.total_seconds())  # 『9000.0』と出力される（2.5時間 × 3600秒）

# イベントまでの残り時間を計算する
event = datetime(2025, 12, 31, 23, 59, 59)
remaining = event - now
if remaining.days >= 0:
    print(f'イベントまであと{remaining.days}日です。')

# timedelta同士の演算もできる
d1 = timedelta(days=5)
d2 = timedelta(days=3)
print(d1 + d2)          # 『8 days, 0:00:00』と出力される
print(d1 - d2)          # 『2 days, 0:00:00』と出力される
print(d1 * 2)           # 『10 days, 0:00:00』と出力される

python3 datetime_timedelta.py
2025-04-22
2025-03-16
2025年04月18日 13:00
9236日が経過しました。
9000.0
イベントまであと260日です。
8 days, 0:00:00
2 days, 0:00:00
10 days, 0:00:00

よくあるミス1: timedeltaで時間の差を求める際の単位ミス

『timedelta.seconds』は「日を除いた秒数」（0〜86399）を返します。日をまたぐ場合は全体の秒数を得るために『total_seconds()』を使います。

NG

from datetime import timedelta

delta = timedelta(days=2, hours=3)

# .seconds は日を除いた秒数（10800秒 = 3時間）
print(delta.seconds)  # 10800（日の部分は含まれない）

OK

from datetime import timedelta

delta = timedelta(days=2, hours=3)

# total_seconds() で全体の秒数を取得
print(delta.total_seconds())  # 183600.0（2日3時間 = 183600秒）
print(int(delta.total_seconds()) // 3600)  # 51（総時間数）

よくあるミス2: timedeltaにmonthsやyearsは使えない

『timedelta』は日数・秒数・マイクロ秒での操作をサポートしますが、月・年の加算はサポートしていません。月・年の演算には『dateutil』ライブラリや手動計算が必要です。

NG 2

from datetime import timedelta

# timedelta に months/years パラメータはない
# timedelta(months=1)  # TypeError: __new__() got an unexpected keyword argument 'months'

OK 2

from datetime import date, timedelta

# 日数で近似する（30日 ≈ 1か月）
today = date(2025, 4, 15)
approx_month_later = today + timedelta(days=30)
print(approx_month_later)  # 2025-05-15

# dateutil.relativedelta を使う（pip install python-dateutil）
from dateutil.relativedelta import relativedelta
exact_month_later = today + relativedelta(months=1)
print(exact_month_later)  # 2025-05-15

『timedelta』は日時同士の差として自動的に生成されます。例えば『datetime_A - datetime_B』の結果は『timedelta』オブジェクトになります。この仕組みを使うと、誕生日からの日数・イベントまでの残り日数・作業時間の計算などが直感的に書けます。

『timedelta.days』と『timedelta.seconds』は期間の内訳を返します。たとえば『timedelta(hours=25)』の場合、『days』は『1』、『seconds』は『3600』になります。総秒数が必要なときは『days』と『seconds』を個別に計算せず、『total_seconds()』を使います。

日時オブジェクトの生成は『datetime.datetime() / datetime.date() / datetime.time()』を、書式変換は『日時.strftime() / datetime.strptime()』を参照してください。