Pendulum: Pythonの日時操作を劇的に改善するライブラリ徹底解説 🕰️

Pythonで日付や時刻を扱う際、標準ライブラリの datetime モジュールを使うのが一般的です。しかし、タイムゾーンの扱いや、月や年単位での直感的な加減算、柔軟な文字列パースなど、もう少し便利だったらな…と感じる場面も少なくありません。 そんな datetime の「かゆいところに手が届く」存在として開発されたのが、サードパーティライブラリの Pendulum です。 Pendulumは、Python標準の datetime クラスを継承しつつ、より使いやすく、より強力な機能を提供します。特にタイムゾーンの扱いは秀逸で、面倒なタイムゾーン変換やサマータイム（DST）の考慮を簡単に行えます。 この記事では、Pendulumの基本的な使い方から、便利な機能、他のライブラリとの違いまで、詳しく解説していきます。

インストール方法

Pendulumはpipを使って簡単にインストールできます。

pip install pendulum
      

もし、後述するテスト用の機能（時間を固定したり進めたりする機能）も使いたい場合は、以下のように [test] をつけてインストールします。

pip install pendulum[test]
      

Poetry を使用している場合は、以下のコマンドでインストールできます。

poetry add pendulum
# テスト用機能を含む場合
poetry add pendulum --extras "test"
      

最新版では Python 3.7 のサポートが終了し、Python 3.8 以降が必要となっています。また、内部実装の一部が Rust で書き直されるなどの変更がありました (バージョン3.0.0, 2023-12-16)。

基本的な使い方

Pendulumは、標準の datetime オブジェクトの「ドロップインリプレースメント」として設計されています。これは、datetime を使っていたコードの多くを、そのままPendulumのオブジェクトに置き換えても動作する（または、わずかな修正で動作する）ことを意味します。

現在時刻の取得

現在の日時を取得するには pendulum.now() を使います。標準の datetime.now() と異なり、デフォルトで実行環境のローカルタイムゾーン情報が付与された「aware」なオブジェクトが返されます。

import pendulum

# 現在時刻 (ローカルタイムゾーン)
now = pendulum.now()
print(now)
# 例: 2025-04-05T10:19:00.123456+09:00 (実行環境が日本時間の場合)
print(now.timezone_name)
# 例: Asia/Tokyo

# UTCでの現在時刻
now_utc = pendulum.now('UTC')
print(now_utc)
# 例: 2025-04-05T01:19:00.123456+00:00
print(now_utc.timezone_name)
# UTC

# 他にも便利なメソッドが用意されている
today = pendulum.today()       # 今日の日付 (00:00:00)
tomorrow = pendulum.tomorrow() # 明日の日付 (00:00:00)
yesterday = pendulum.yesterday() # 昨日の日付 (00:00:00)

print(today)
print(tomorrow)
print(yesterday)
      

today(), tomorrow(), yesterday() もタイムゾーンを指定できます。

特定の日時の生成

特定の日時を表すオブジェクトを生成するには pendulum.datetime() や pendulum.local() を使います。datetime() はデフォルトでUTCタイムゾーン、local() はローカルタイムゾーンになります。タイムゾーンは tz 引数で指定できます。

import pendulum

# 年月日を指定 (デフォルトはUTC)
dt1 = pendulum.datetime(2023, 10, 26)
print(dt1) # 2023-10-26T00:00:00+00:00
print(dt1.timezone_name) # UTC

# 年月日時分秒を指定 (デフォルトはUTC)
dt2 = pendulum.datetime(2023, 10, 26, 15, 30, 0)
print(dt2) # 2023-10-26T15:30:00+00:00

# タイムゾーンを指定 (IANA Time Zone Database の名前を使用)
dt_tokyo = pendulum.datetime(2023, 10, 26, 15, 30, 0, tz='Asia/Tokyo')
print(dt_tokyo) # 2023-10-26T15:30:00+09:00
print(dt_tokyo.timezone_name) # Asia/Tokyo

# local() を使うとローカルタイムゾーンになる
dt_local = pendulum.local(2023, 10, 26, 15, 30, 0)
print(dt_local) # 実行環境に依存 (例: 2023-10-26T15:30:00+09:00)
print(dt_local.timezone_name) # 実行環境に依存 (例: Asia/Tokyo)

# タイムゾーンオブジェクトを作成して渡すことも可能
tz_paris = pendulum.timezone('Europe/Paris')
dt_paris = pendulum.datetime(2023, 10, 26, 15, 30, 0, tz=tz_paris)
print(dt_paris) # 2023-10-26T15:30:00+02:00 (DST適用期間の場合)
print(dt_paris.timezone_name) # Europe/Paris

# naive (タイムゾーン情報なし) オブジェクトが必要な場合 (非推奨)
naive_dt = pendulum.naive(2023, 10, 26, 15, 30, 0)
print(naive_dt) # 2023-10-26T15:30:00
# print(naive_dt.timezone_name) # AttributeError
      

Pendulumはタイムゾーン情報を持つ「aware」な日時オブジェクトの使用を推奨しています。

属性へのアクセス

Pendulumオブジェクトは、datetime オブジェクトと同様に、年、月、日などの属性にアクセスできます。さらに、曜日、年の何日目か、月の何週目かなど、より多くの便利な属性を提供しています。

import pendulum

dt = pendulum.datetime(2023, 10, 26, 15, 30, 45, 123456, tz='Asia/Tokyo')

print(f"年: {dt.year}")         # 2023
print(f"月: {dt.month}")        # 10
print(f"日: {dt.day}")          # 26
print(f"時: {dt.hour}")         # 15
print(f"分: {dt.minute}")       # 30
print(f"秒: {dt.second}")       # 45
print(f"マイクロ秒: {dt.microsecond}") # 123456

print(f"曜日 (月曜0): {dt.day_of_week}")      # 3 (木曜日)
print(f"曜日 (ISO, 月曜1): {dt.isoweekday()}") # 4
print(f"年の何日目か: {dt.day_of_year}")     # 299
print(f"月の何週目か: {dt.week_of_month}")   # 4
print(f"年の何週目か (ISO): {dt.week_of_year}") # 43
print(f"月の日数: {dt.days_in_month}")   # 31
print(f"四半期: {dt.quarter}")        # 4
print(f"タイムゾーン: {dt.timezone_name}")   # Asia/Tokyo
print(f"UTCオフセット (秒): {dt.offset}")  # 32400 (9時間 * 3600秒)
print(f"DST適用中か: {dt.is_dst()}")     # False (日本の場合は常にFalse)
print(f"うるう年か: {dt.is_leap_year()}") # False
      

タイムゾーン処理 ✨Pendulumの真骨頂✨

Pendulumの最も強力な機能の一つが、タイムゾーンの扱いです。IANAタイムゾーンデータベース (https://www.iana.org/time-zones) に基づいたタイムゾーン名を文字列で指定するだけで、面倒なタイムゾーン変換やサマータイム（Daylight Saving Time, DST）の切り替えを自動的に処理してくれます。

import pendulum

# ロンドン時間で日時を作成 (2024年3月31日 00:59:59 - DST切り替え直前)
dt_london_before = pendulum.datetime(2024, 3, 31, 0, 59, 59, tz='Europe/London')
print(f"ロンドン (切り替え前): {dt_london_before} ({dt_london_before.offset_hours}h)")
# ロンドン (切り替え前): 2024-03-31T00:59:59+00:00 (0h)

# 1秒加算すると、DSTが開始され、タイムゾーンオフセットが変わる
dt_london_after = dt_london_before.add(seconds=1)
print(f"ロンドン (切り替え後): {dt_london_after} ({dt_london_after.offset_hours}h)")
# ロンドン (切り替え後): 2024-03-31T02:00:00+01:00 (1h) ← 1時台が飛んで2時になる！

# タイムゾーン間の変換も簡単
dt_tokyo = dt_london_after.in_timezone('Asia/Tokyo')
print(f"東京時間: {dt_tokyo} ({dt_tokyo.offset_hours}h)")
# 東京時間: 2024-03-31T10:00:00+09:00 (9h)

dt_newyork = dt_tokyo.in_timezone('America/New_York')
print(f"ニューヨーク時間: {dt_newyork} ({dt_newyork.offset_hours}h)")
# ニューヨーク時間: 2024-03-31T21:00:00-04:00 (-4h) ← NYもDST適用中

# .now() で取得したローカル時間を別のタイムゾーンに変換
now_local = pendulum.now()
print(f"\nローカル時間: {now_local}")
now_utc_converted = now_local.in_timezone('UTC')
print(f"UTCに変換: {now_utc_converted}")
      

in_timezone() メソッドを使うだけで、指定したタイムゾーンでの時刻に簡単に変換できます。内部的にUTCに変換してから計算されるため、異なるタイムゾーン間での比較や演算も正確に行われます。 標準ライブラリの datetime でタイムゾーンを扱うには、pytz などの別のライブラリが必要になることが多く、DSTの境界での挙動などを自分で注意深く管理する必要がありましたが、Pendulumを使えばその手間が大幅に省けます。

日時の加算・減算

Pendulumでは、add() および subtract() メソッドを使って、直感的に日時の加算・減算ができます。years, months, weeks, days, hours, minutes, seconds といったキーワード引数で指定します。

import pendulum

dt = pendulum.datetime(2023, 1, 31, 12, 0, 0)
print(f"元の日時: {dt}")

# 1年加算
dt_plus_1y = dt.add(years=1)
print(f"1年後: {dt_plus_1y}") # 2024-01-31 12:00:00+00:00 (うるう年を考慮)

# 1ヶ月加算 (月末処理が賢い！)
dt_plus_1m = dt.add(months=1)
print(f"1ヶ月後: {dt_plus_1m}") # 2023-02-28 12:00:00+00:00 (2月は31日がないため28日になる)

# 3日減算
dt_minus_3d = dt.subtract(days=3)
print(f"3日前: {dt_minus_3d}") # 2023-01-28 12:00:00+00:00

# 2時間30分加算
dt_plus_hm = dt.add(hours=2, minutes=30)
print(f"2時間30分後: {dt_plus_hm}") # 2023-01-31 14:30:00+00:00

# 複合的な加減算も可能
dt_complex = dt.add(years=1, months=2).subtract(days=5, hours=3)
print(f"複雑な計算後: {dt_complex}") # 2024-03-26 09:00:00+00:00
      

特に月単位の加減算において、月末の日付が存在しない場合に自動的に調整してくれる点（例：1月31日の1ヶ月後は2月28日）は、標準の timedelta では扱いにくい部分であり、Pendulumの便利な点です。

期間 (Period) と差分 (Duration)

Pendulumは、日時の「差」を扱うための2つのクラスを提供します。

• Duration: 時間の「長さ」を表します（例: 3日と5時間）。標準の timedelta の拡張版で、年や月単位も扱えます。
• Period: 二つの特定の DateTime インスタンス間の「期間」を表します。開始日時と終了日時を保持しており、その期間を反復処理することも可能です。

Duration

pendulum.duration() で作成したり、DateTime オブジェクト同士の引き算（差が小さい場合）で得られます。

import pendulum

# Duration を作成
dur1 = pendulum.duration(days=2, hours=3, minutes=30)
print(f"Duration 1: {dur1}")
print(f"  総秒数: {dur1.total_seconds()}") # 185400.0
print(f"  総時間数: {dur1.total_hours()}") # 51.5
print(f"  週単位: {dur1.weeks}") # 0
print(f"  日単位 (週を除く): {dur1.remaining_days}") # 2
print(f"  時間単位 (日を除く): {dur1.hours}") # 3
print(f"  分単位 (時間を除く): {dur1.minutes}") # 30
print(f"  人間が読みやすい形式: {dur1.in_words(locale='ja')}") # 2日 3時間 30分

dur2 = pendulum.duration(years=1, months=6)
print(f"\nDuration 2: {dur2}")
print(f"  年単位: {dur2.years}") # 1
print(f"  月単位 (年を除く): {dur2.months}") # 6
print(f"  人間が読みやすい形式: {dur2.in_words(locale='ja')}") # 1年 6ヶ月

# DateTime に Duration を加算
dt = pendulum.datetime(2023, 1, 1)
dt_added = dt + dur1
print(f"\n日時 + Duration 1: {dt_added}") # 2023-01-03 03:30:00+00:00
      

in_words() メソッドを使うと、「〇日と〇時間」のような自然な言語で期間を表示できます。ロケールを指定すれば日本語表示も可能です（例: locale='ja'）。

Period

二つの DateTime オブジェクトの引き算で得られます。

import pendulum

start = pendulum.datetime(2023, 1, 15, 10, 0, 0)
end = pendulum.datetime(2023, 1, 18, 14, 30, 0)

# Period を作成 (引き算)
period = end - start
print(f"Period: {period}")
print(f"  開始日時: {period.start}")
print(f"  終了日時: {period.end}")
print(f"  日数: {period.in_days()}") # 3
print(f"  時間数: {period.in_hours()}") # 76
print(f"  週数: {period.in_weeks()}") # 0
print(f"  人間が読みやすい形式: {period.in_words(locale='ja')}") # 3日 4時間 30分

# Period は反復処理が可能 (デフォルトは1日ごと)
print("\n期間内の日付:")
for dt in period:
    print(dt.to_date_string())
# 2023-01-15
# 2023-01-16
# 2023-01-17

# 間隔を指定して反復処理 (例: 12時間ごと)
print("\n期間内 (12時間ごと):")
for dt in period.range('hours', 12):
    print(dt)
      

Periodオブジェクトは、特定の期間における処理（例えば、日ごとの集計など）を行う際に非常に便利です。

人間が読みやすい形式 (Human Readable)

ある日時が現在から見て「どれくらい前/後」なのかを、「3時間前」「2日後」のような分かりやすい文字列で表現したい場合があります。Pendulumでは diff_for_humans() メソッドでこれを簡単に実現できます。

import pendulum

# 現在時刻からの相対的な時間を計算
now = pendulum.now()

past_dt = now.subtract(hours=3, minutes=15)
future_dt = now.add(days=5)
far_future_dt = now.add(years=2)

# diff_for_humans() を使う
# デフォルトでは現在時刻と比較される
print(f"{past_dt} は: {past_dt.diff_for_humans(locale='ja')}")
# 例: 2025-04-05 07:04:00+09:00 は: 3時間前

print(f"{future_dt} は: {future_dt.diff_for_humans(locale='ja')}")
# 例: 2025-04-10 10:19:00+09:00 は: 5日後

# 特定の日時と比較することも可能
base_dt = pendulum.datetime(2023, 1, 1)
target_dt = pendulum.datetime(2023, 3, 10)
print(f"\n{target_dt} は {base_dt} から見て: {target_dt.diff_for_humans(base_dt, absolute=True, locale='ja')}")
# 2023-03-10 00:00:00+00:00 は 2023-01-01 00:00:00+00:00 から見て: 2ヶ月差

# absolute=False にすると「前」「後」が付く
print(f"{target_dt} は {base_dt} から見て: {target_dt.diff_for_humans(base_dt, absolute=False, locale='ja')}")
# 2023-03-10 00:00:00+00:00 は 2023-01-01 00:00:00+00:00 から見て: 2ヶ月後
      

locale 引数で言語を指定でき、absolute=True にすると「〇〇差」、absolute=False (デフォルト) にすると「〇〇前」「〇〇後」という表現になります。

フォーマットとパース

日時の文字列表現と DateTime オブジェクトの相互変換（フォーマットとパース）も、Pendulumは得意としています。

フォーマット (オブジェクト → 文字列)

format() メソッドを使用します。標準の strftime とは異なる、より直感的で豊富なフォーマット指定子を利用できます。角括弧 [] で囲まれた文字はそのまま出力されます。

import pendulum

dt = pendulum.datetime(2023, 10, 26, 15, 30, 45, 123456, tz='Asia/Tokyo')

# 一般的なフォーマット
print(dt.format('YYYY-MM-DD HH:mm:ss'))     # 2023-10-26 15:30:45
print(dt.format('YYYY/MM/DD dddd'))         # 2023/10/26 木曜日 (ロケールに依存)
print(dt.format('MMM Do, YYYY h:mm A'))     # Oct 26th, 2023 3:30 PM (ロケールに依存)
print(dt.format('YYYY年M月D日 H時m分s秒'))   # 2023年10月26日 15時30分45秒

# [] を使ってリテラル文字をエスケープ
print(dt.format('YYYY-MM-DD [at] HH:mm'))   # 2023-10-26 at 15:30

# マイクロ秒やタイムゾーンオフセットも
print(dt.format('YYYY-MM-DD HH:mm:ss.SSSSSS ZZ')) # 2023-10-26 15:30:45.123456 +0900
print(dt.format('YYYY-MM-DD HH:mm:ss Z'))         # 2023-10-26 15:30:45 +09:00

# 組み込みの便利なフォーマットメソッド
print(dt.to_iso8601_string())      # 2023-10-26T15:30:45+09:00
print(dt.to_rfc3339_string())      # 2023-10-26T15:30:45+09:00
print(dt.to_date_string())         # 2023-10-26
print(dt.to_time_string())         # 15:30:45
print(dt.to_datetime_string())     # 2023-10-26 15:30:45
print(dt.to_day_datetime_string()) # Thu, Oct 26, 2023 3:30 PM (ロケールに依存)
print(dt.to_atom_string())         # 2023-10-26T15:30:45+09:00
print(dt.to_cookie_string())       # Thursday, 26-Oct-2023 15:30:45 JST
print(dt.to_rss_string())          # Thu, 26 Oct 2023 15:30:45 +0900
print(dt.to_w3c_string())          # 2023-10-26T15:30:45+09:00
      

利用可能なフォーマット指定子の詳細は、Pendulumの公式ドキュメントを参照してください。一般的な YYYY, MM, DD, HH, mm, ss などが使えます。

パース (文字列 → オブジェクト)

pendulum.parse() は、様々な形式の日時文字列を自動的に解析して DateTime オブジェクトに変換しようと試みます。ISO 8601形式やRFC 3339形式など、多くの一般的なフォーマットに対応しています。

import pendulum

# parse() による自動解析
dt1 = pendulum.parse('2023-10-26T15:30:45+09:00')
print(dt1) # 2023-10-26T15:30:45+09:00

dt2 = pendulum.parse('2023-10-26 15:30:45') # タイムゾーンがない場合はUTC扱い
print(dt2) # 2023-10-26T15:30:45+00:00

dt3 = pendulum.parse('26 Oct 2023 15:30:45 JST')
print(dt3) # 2023-10-26T15:30:45+09:00

dt4 = pendulum.parse('20231026') # 日付のみもOK
print(dt4) # 2023-10-26T00:00:00+00:00

# タイムゾーンを指定することも可能 (元の文字列にTZがない場合)
dt5 = pendulum.parse('2023-10-26 15:30:45', tz='Asia/Tokyo')
print(dt5) # 2023-10-26T15:30:45+09:00

# 厳密でないパース (dateutil のパーサーを利用)
# 少し曖昧な形式も解釈できる場合がある
try:
    # strict=True (デフォルト) ではエラーになる可能性がある形式
    dt_strict_error = pendulum.parse('10/26/2023')
except pendulum.parsing.exceptions.ParserError as e:
    print(f"Strict parse error: {e}")

dt6 = pendulum.parse('10/26/2023', strict=False)
print(dt6) # 2023-10-26T00:00:00+00:00

# 特定のフォーマットを指定してパース: from_format()
# parse() で解釈できない独自のフォーマットの場合に使う
dt7 = pendulum.from_format('2023年10月26日 15時30分', 'YYYY年M月D日 H時m分', tz='Asia/Tokyo')
print(dt7) # 2023-10-26T15:30:00+09:00
      

parse() は非常に強力ですが、予期しない形式の文字列が入力される可能性がある場合は、try...except でエラー処理を行うか、from_format() で明確にフォーマットを指定する方が安全です。strict=False オプションは、内部で dateutil ライブラリのパーサーを使用します。

他の日時ライブラリとの比較

Pythonには日時を扱うためのライブラリがいくつか存在します。Pendulumがそれらとどう違うのか、主なものと比較してみましょう。

datetime (標準ライブラリ): 基本的な日時操作は可能ですが、タイムゾーンの扱い（特にDST）や月・年単位の計算が煩雑になりがちです。AwareオブジェクトとNaiveオブジェクトの概念を理解する必要があります。

dateutil: datetime を強力に拡張するライブラリです。relativedelta による相対的な日付計算や、parser.parse による柔軟な文字列解析が特徴です。タイムゾーン処理 (dateutil.tz) も pytz よりシンプルに扱える場合があります。Pendulumは dateutil の機能の多くを内包し、さらに直感的なAPIを提供しています。

pytz: タイムゾーン情報を提供することに特化したライブラリです。多くのライブラリ（古いバージョンのDjangoなど）で利用されてきましたが、datetime 標準の zoneinfo (Python 3.9+) や dateutil.tz、そしてPendulumの登場により、直接利用する場面は減ってきています。

Pendulum: datetime のドロップインリプレースメントとして、使いやすさと高機能を両立しています。特にタイムゾーン処理と直感的なAPIが優れており、dateutil の機能も取り込んでいます。一方で、datetime 単体よりは依存関係が増え、わずかにパフォーマンスが低下する可能性はあります（ただし、多くの場合問題にならないレベルです）。

これから新しくPythonで日時処理を行うプロジェクトを開始する場合や、既存のコードのタイムゾーン処理などで苦労している場合には、Pendulumは非常に有力な選択肢となるでしょう。

便利な機能・Tips

Pendulumには、他にも開発を助ける便利な機能があります。

テスト用の時間操作 ⏱️

日時が関わる処理をテストする際、時間を固定したり、特定の時点に進めたりしたいことがあります。Pendulumでは [test] オプション付きでインストールすることで、pendulum.travel_to() や pendulum.freeze() といったヘルパー関数が利用可能になります。

import pendulum
import time

# この機能を使うには pip install pendulum[test] が必要

# テストのために時間を固定する
frozen_time = pendulum.datetime(2023, 1, 1, 12, 0, 0)
pendulum.travel_to(frozen_time)

print(f"固定された現在時刻: {pendulum.now()}") # 2023-01-01T12:00:00+00:00

# 時間を進める (travel_to は時間を進めることもできる)
pendulum.travel(seconds=30)
print(f"30秒進めた時刻: {pendulum.now()}") # 2023-01-01T12:00:30+00:00

# freeze() を使うと、travel() で時間は進まなくなる
pendulum.freeze(frozen_time.add(hours=1))
print(f"\n再度固定された時刻: {pendulum.now()}") # 2023-01-01T13:00:00+00:00
pendulum.travel(minutes=10) # freeze中はtravelしても時間は進まない
print(f"freeze中に10分進めても: {pendulum.now()}") # 2023-01-01T13:00:00+00:00

# 元の時間の流れに戻す
pendulum.travel_back()
print(f"\n元の時間に戻した現在時刻: {pendulum.now()}") # 実際の現在時刻が表示される
      

travel_to() は指定した時刻に「移動」し、その後 travel() で時間を進めることができます。freeze() は指定した時刻で完全に「凍結」させます。travel_back() で元の時間の流れに戻せます。 これらの機能は、テストコード内で時間をコントロールしたい場合に非常に役立ちます。

定数

曜日や月、世紀あたりの年数など、便利な定数も定義されています。

import pendulum

print(f"月曜日 (定数): {pendulum.MONDAY}")             # 1 (ISO 8601 形式)
print(f"日曜日 (定数): {pendulum.SUNDAY}")             # 7 (ISO 8601 形式)

print(f"1分あたりの秒数: {pendulum.SECONDS_PER_MINUTE}") # 60
print(f"1時間あたりの分数: {pendulum.MINUTES_PER_HOUR}")   # 60
print(f"1日あたりの時間数: {pendulum.HOURS_PER_DAY}")     # 24
print(f"1週間あたりの日数: {pendulum.DAYS_PER_WEEK}")     # 7
print(f"1世紀あたりの年数: {pendulum.YEARS_PER_CENTURY}") # 100
print(f"1千年紀あたりの年数: {pendulum.YEARS_PER_MILLENNIUM}") # 1000
      

これらの定数を使うことで、コードの可読性を高めることができます。

まとめ

Pendulumは、Pythonの標準 datetime モジュールの機能を大幅に拡張し、より直感的で使いやすいAPIを提供する優れたライブラリです。 特に、タイムゾーン処理の簡便さと正確さは、他のライブラリと比較しても際立っています。DSTの切り替えなどを意識することなく、異なるタイムゾーン間での日時計算や変換を簡単に行えます。

また、add()/subtract() による直感的な日時の加減算、Duration/Period による期間や差分の扱いやすさ、diff_for_humans() や format() による人間が読みやすい形式への変換、parse() による柔軟な文字列解析など、多くの便利な機能が提供されています。

標準の datetime で少し不便を感じている方、タイムゾーン処理に悩まされている方は、ぜひPendulumの導入を検討してみてください。きっと、Pythonでの日時操作がより快適になるはずです！🚀