Python の pendulum でタイムゾーン対応の日時処理を簡潔に書く

pendulum は Python の日時処理をモダンに書き直したライブラリです。タイムゾーン対応がデフォルトで組み込まれており、直感的な API で日時操作ができます。

インストール

pip でインストールできます。

pip install pendulum

基本的な使い方

pendulum の日時オブジェクトは標準の datetime を継承しているため、既存のコードとも互換性があります。

import pendulum

# 現在時刻（タイムゾーン付き）
now = pendulum.now()
print(now)  # 2025-01-15T14:30:00+09:00

# UTC で取得
utc_now = pendulum.now("UTC")
print(utc_now)

# 特定の日時を作成
dt = pendulum.datetime(2025, 1, 15, 10, 30, tz="Asia/Tokyo")
print(dt)

標準の datetime.now() と違い、常にタイムゾーン情報を持った aware な日時オブジェクトが返ります。

タイムゾーン変換

タイムゾーンの変換が非常に簡単です。

import pendulum

# 東京時間
tokyo = pendulum.now("Asia/Tokyo")
print(f"東京: {tokyo}")

# ニューヨーク時間に変換
new_york = tokyo.in_timezone("America/New_York")
print(f"NY: {new_york}")

# UTC に変換
utc = tokyo.in_timezone("UTC")
print(f"UTC: {utc}")

in_timezone() メソッドで直感的に変換できます。

日時の加減算

add() と subtract() で日時の加減算を行います。

import pendulum

now = pendulum.now()

# 3日後
print(now.add(days=3))

# 2ヶ月前
print(now.subtract(months=2))

# 1年3ヶ月後
print(now.add(years=1, months=3))

標準の timedelta では扱えない月や年も、pendulum なら自然に書けます。月末の処理も自動で調整されるため、31日の1ヶ月後が存在しない日になる心配もありません。

人間が読みやすい差分表示

diff_for_humans() は差分を自然言語で表示してくれます。

import pendulum

now = pendulum.now()
past = now.subtract(hours=2, minutes=30)

print(past.diff_for_humans())  # "2 hours ago"

# 日本語で表示
pendulum.set_locale("ja")
print(past.diff_for_humans())  # "2時間前"

「○分前」「○日後」といった表示が必要な UI で重宝します。

期間の操作

period() を使うと、2つの日時間の期間を扱えます。

import pendulum

start = pendulum.datetime(2025, 1, 1)
end = pendulum.datetime(2025, 12, 31)

period = pendulum.period(start, end)

print(f"期間: {period.in_days()}日")
print(f"期間: {period.in_months()}ヶ月")

期間内の日付をイテレートすることもできます。

import pendulum

start = pendulum.datetime(2025, 1, 1)
end = pendulum.datetime(2025, 1, 5)

for dt in pendulum.period(start, end):
    print(dt.to_date_string())

フォーマットとパース

フォーマットは format() メソッド、パースは parse() 関数を使います。

import pendulum

dt = pendulum.now()

# フォーマット
print(dt.format("YYYY年MM月DD日 HH:mm"))  # 2025年01月15日 14:30

# パース（自動認識）
parsed = pendulum.parse("2025-01-15T10:30:00")
print(parsed)

# タイムゾーン指定でパース
parsed = pendulum.parse("2025-01-15 10:30:00", tz="Asia/Tokyo")
print(parsed)

datetime との互換性

pendulum のオブジェクトは datetime を継承しているため、既存の関数にそのまま渡せます。

import pendulum
from datetime import datetime

def legacy_function(dt: datetime):
    return dt.strftime("%Y-%m-%d")

p = pendulum.now()
print(legacy_function(p))  # 問題なく動作

pendulum vs dateutil

どちらを選ぶかは好みとプロジェクトの要件次第です。

dateutil

標準ライブラリの拡張。軽量で依存が少ない。

pendulum

日時処理を再設計。API が統一されていて学習しやすい。

タイムゾーン対応を重視するプロジェクトや、チーム全体で統一した書き方を採用したい場合は pendulum がおすすめです。一方、既存プロジェクトへの追加や軽量さを重視するなら dateutil のほうが適しているかもしれません。