datetime.timedelta()

from datetime import datetime, timedelta

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

# 日時に期間を加算します。
未来 = 日時 + delta

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

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

from datetime import datetime, timedelta

# 現在から7日後の日時を求めます。
now = datetime.now()
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)
today = datetime.now()
diff = today - 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 - datetime.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』と出力されます。

『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()』を参照してください。