なぜPendulumはPythonで最も呪われた「+」演算子を書かなければならなかったのか
Why Pendulum had to write the most cursed "+" operator in all of Python (dev.arie.bovenberg.net)
要約
PythonのdatetimeライブラリであるPendulumは、timedeltaを加算する際の「+」演算子で、呼び出しスタックを調べて動作を決定するという、非常に珍しい実装を採用しています。これは、夏時間(DST)の切り替わりを考慮した正確な時刻計算というPendulumの約束と、標準ライブラリとの互換性という別の約束との間の衝突を解決するための苦肉の策でした。このハックは最近のバージョンで削除されつつありますが、その設計思想は依然として重要です。
全文翻訳
なぜPendulumはPython史上最も呪われた「+」演算子を書かなければならなかったのか
Pendulum は、datetimeを扱うための人気のPythonライブラリです。バージョン3.3まで、その + 演算子は、datetimeライブラリとしても異例なものでした。Pendulumの DateTime オブジェクトに timedelta を加算すると、呼び出しスタック を参照して、どの結果を返すかを決定していたのです。一体なぜ?そして、その理由は?このハック自体は現在削除されていますが、その背後にある設計は依然としてコードに影響を与えています。
更新(2026年10月13日):Pendulum 3.3では、下記で説明されている修正を使用して、呼び出しスタックのチェックが削除されました。この投稿の残りの部分は3.2.0について説明しており、その主な論点は依然として有効です:ハックの背後にある設計は変わっていません。
執筆時点での最新リリースであるPendulum 3.2.0の __add__ メソッド は、標準ライブラリの datetime.__add__() をオーバーライドしています。
def __add__(self, other):
...
caller = traceback.extract_stack(limit=2)[0].name
if caller == "astimezone":
return super().__add__(other)
return self._add_timedelta_(other)
結果は、それを呼び出した関数の名前に依存します。そのため、独自の関数名を変更することで + の結果を変えることができます。
>>> import pendulum
>>> from datetime import timedelta
>>> def astimezone(dt):
... return dt + timedelta(hours=24)
>>> base = pendulum.datetime(2013, 3, 30, 12, tz="Europe/Paris")
>>> base + timedelta(hours=24)
DateTime(2013, 3, 31, 13, ...) # +24時間経過(DSTで1時間スキップ)
>>> astimezone(base)
DateTime(2013, 3, 31, 12, ...) # 壁時計上の+24時間
私は、自身のdatetimeライブラリであるwheneverを開発中に、Pendulumの挙動と比較していてこれに遭遇しました。PendulumはDST[2]の算術処理を正しく行うことで名声を博しており、その + は標準ライブラリのものとは異なる必要があります。それが__add__のself._add_timedelta_(other)ブランチが行っていることです。
しかし、なぜそれを時々しか取らないのでしょうか?そして、これは安価な処理でもありません。呼び出しスタックをたどることで、Pendulumの+演算子は標準ライブラリのものより数百倍遅くなります。
これは必死のハックのように見えますが、慣習的な # すみません、すみません、説明させてください というコメントがありません。誰も、これほど広く使われているライブラリに理由なくこれを搭載しません。一体何が彼らを追い詰めたのでしょうか?
2つの約束
Pendulumは2つの約束でその名を馳せました。
-
DSTを意識した算術処理。標準ライブラリの
+は壁時計上で動作するため、DSTの切り替わりを跨いでtimedeltaを加算すると予期せぬ結果になります。「24時間後」が実際には23時間または25時間後になってしまうのです。Pendulumの+は代わりに経過時間をカウントします。これは他の言語で標準になりつつあるモデル[3]に沿ったものであり、Pendulumを使用する良い理由です。 -
ドロップイン互換性。Pendulumの
DateTimeはdatetimeをサブクラス化し、Durationはtimedeltaをサブクラス化し、TimezoneはZoneInfoをサブクラス化します。あなたの既存のコードや、あなたが使用するあらゆるライブラリは、これらのPendulumのサブクラスを何も変更せずに受け入れます。この機能により、Pendulumを簡単に導入できます。
しかし、この2つの約束の間には対立があります。「ドロップイン置換」は、Pendulumの値を標準ライブラリの値で置き換えても、同じ挙動が得られることを約束します。しかし、DSTを意識した算術処理は、その逆、つまり改善された+、異なる挙動を約束します[4]。
この対立は、コードが標準ライブラリの+演算子に依存しているあらゆる場所で表面化します。たとえそれが直感的でない挙動であっても[5]です。これが最初に破綻するのは、タイムゾーン変換です。datetimeを変換するために、標準ライブラリ自身の機構が中間ステップとしてあなたの値に対して算術処理を行います。
dt.astimezone(paris) # あなたのコード
-> DateTime.astimezone() # Pendulum (Python)
-> datetime.astimezone() # 標準ライブラリ (C)
-> ZoneInfo.fromutc() # 標準ライブラリ (C): dt + offset を計算
-> DateTime.__add__() # Pendulum: どちらの + を意味しましたか?
ZoneInfo.fromutc()は壁時計のセマンティクスを期待して+を呼び出します。しかし、Pendulumのオーバーロードされた+はDSTを意識した算術処理を適用し、DSTの切り替わり付近で1時間ずれた値につながります。
Pendulumは、身動きが取れない状況に置かれています。標準ライブラリの変換ロジック(これは標準ライブラリに属します)を変更することはできませんし、+のオーバーロードを削除することもできません(それはDSTを意識した算術処理という約束を破ることになります)。
その答えは、実行時に推測することです。呼び出し元がどの挙動を期待しているかを。
これが__add__の呼び出しスタックチェックを説明しています。もし呼び出し元がastimezone()という名前の関数であれば、Pendulumは標準ライブラリ経由で変換しているとみなし、標準ライブラリの算術処理(super().__add__(other))を適用します。
他に誰が呼んでいるのか?
呼び出し元を推測することの難しさは、すべての呼び出し元を予測できないことです。Pendulumのハードコードされたチェックは脆弱です。それは1つの名前しかカバーしておらず、Pendulumの制御外にある正確な呼び出しスタックに依存しています。標準ライブラリの算術処理を期待する他のコードは、代わりにPendulumのものを受け取ることになります。例えば、dateutilのタイムゾーンへの変換は、異なる呼び出しスタックを通り、結果はサイレントにナイーブ(naive)になり、UTCオフセットからずれます(#820)。
>>> from dateutil import tz
>>> d = pendulum.datetime(2024, 7, 1, 12, tz="UTC")
>>> d.astimezone(tz.gettz("Europe/Paris"))
DateTime(2024, 7, 1, 12, 0, 0) # naive — そして14:00ではない
PyPy上では、Pendulum自身の変換でさえ異なる呼び出しスタックを通り、間違ったブランチを取ります。2024年3月31日午前1時30分UTCがin_tz("Europe/Paris")で午前4時30分になり、1時間ずれています。
そして、推測は無料ではありません。呼び出し元の名前を知るために、traceback.extract_stack()は各フレームを要約します。オペレーティングシステムにソースファイルが変更されたか(stat())を尋ね、ソースの行を読み取ります。全体として、+は約600倍遅くなります[6]。
>>> from datetime import datetime
>>> from zoneinfo import ZoneInfo
>>> from timeit import timeit
>>> hour = timedelta(hours=1)
>>> std = datetime(2024, 1, 1, tzinfo=ZoneInfo("Europe/Paris"))
>>> pdl = pendulum.datetime(2024, 1, 1, tz="Europe/Paris")
>>> timeit("std + hour", globals=globals(), number=100_000)
0.0069 # 秒
>>> timeit("pdl + hour", globals=globals(), number=100_000)
4.36 # 秒
推測してみて?
Pendulumは、情報が欠落している場合に、それを補うために推測をします。それほど劇的ではありませんが、他の場所でも推測を行います。
- タイムゾーンがない?
parse()とinstance()はUTCを仮定します。 - 日付のない時刻?
parse("12:00")はあなたのマシンの今日の日付を取ります。 - DSTでスキップされる壁時計時刻? Pendulumは標準ライブラリとは逆の方向に
foldを読み取ります。 - そして
+? 上記のように:誰が尋ねているかによります。
それぞれの推測は、それ自体では合理的に見えるかもしれません。しかし、この推測には4つの問題があります。
-
推測は、正直に不完全な値を自信を持って間違った値に変える可能性があります。タイムゾーンのないタイムスタンプは、UTCのサーバーから、あるいは東京のユーザーから発生した可能性があります。Pendulumは「不明」を「UTC」に変えることで、その区別を曖昧にし、下流のコードは違いを区別できなくなります。
-
推測は、あなたのコードが言及していないものに結果を依存させます:現在の時刻、マシンのタイムゾーン、関数の名前。
parse()は不純な関数になります:12:00を渡した結果は、それがいつ、どこで実行されたかに依存します。 -
推測は拡張できますが、すべてのユースケースをカバーすることは決してできません。常に別の呼び出し元、別の入力、別のタイムゾーンがあり、それは予測されていませんでした。
-
推測は取り消せません。Pendulumを使用するすべてのプログラムは、それが正確に推測する方法に依存しています。推測を取り除くことは、既存のプログラムが計算するものをサイレントに変更することにもなります。
まあ、1つの例外を除いて:+の推測です。
Pendulumは必要だったのか?
では、Pendulumはこの+演算子を書く必要があったのでしょうか?fromutc()の対立は確かに回避策を必要としました[7]が、呼び出しスタックをたどることが唯一の選択肢ではありません。
最もクリーンな回避策は、推測を完全に削除することです。astimezone()は標準ライブラリにプレーンなdatetimeを渡し、その後で結果を再度ラップすることができます。
def astimezone(self, tz=None):
plain = datetime(self.year, ..., tzinfo=self.tzinfo, fold=self.fold)
dt = plain.astimezone(tz) # 標準ライブラリの `+` のみを実行
return self.__class__(dt.year, ..., tzinfo=dt.tzinfo, fold=dt.fold)
私はこれをプルリクエストとして提案しました。これはPendulum 3.3でリリースされました。
これにより、__add__は推測するものがなくなり、上記のバグは消滅します。興味深いことに、Pendulum自身のadd()メソッドはすでにこの方法で動作しています。そして+は5倍高速になります:約600倍遅い状態から約120倍遅い状態に。残りの遅延は、純粋なPythonで書かれたPendulumの算術処理自体のコストです。
したがって、はい、Pendulumは追い詰められていました。残念ながら、それはかなり高価な抜け道を選びました[8]。
これのどれも根本的な問題を解決するものではありません。Pendulumが制御していないすべてのコードに到達できる回避策はありません。datetimeを期待しているのにPendulumのDateTimeを渡されたコードは、それが準備ができているかどうかにかかわらず、Pendulumの+を受け取ることになります。最小限の例です。
>>> d = pendulum.datetime(2024, 7, 1, 12, tz="UTC")
>>> datetime.astimezone(d, ZoneInfo("Europe/Paris"))
DateTime(2024, 7, 1, 12, 0, 0) # naive — そして14:00ではない
これを修正する唯一の方法は、Pendulumが2つの約束のどちらかを破ることです:DSTを意識した算術処理を削除するか、ドロップインサブクラスをやめるかです[9]。
今後は?
もしあなたがすでにPendulumを使用しているなら、パニックになる必要はありません。しかし、以下の点に注意してください。
- サードパーティのタイムゾーン(
dateutilのものなど)に変換する場合。 - PyPyで実行する場合。
- ホットループで
+を使用する場合。 - 信頼できない、または不完全な文字列をパースする場合。
datetimeが期待される場所にPendulumの値を渡す場合。
Pendulum 3.3は最初の2つを修正し、+を遅くなくするので、アップグレードする価値があります。最後の2つはPendulumの設計に起因しており、破壊的な変更なしには修正できません。
もしゼロから始めるなら、他に2つの道があります。
- 標準ライブラリの
datetimeを使用し続ける。それは高速で、堅牢で、よくメンテナンスされています。コスト:その直感に反する+と、その他の落とし穴に慣れる必要があります[10]。 - または、落とし穴を修正するライブラリを採用する。Pendulumは、ドロップイン置換がどのように機能しないかを示しています。これが
wheneverがするトレードオフです:datetimeをサブクラス化しませんが、その代わりに、ナイーブとアウェアが混在できず、算術処理が他の言語で標準になりつつあるモデルに従う型安全なAPIが得られます[3]。何もサイレントに推測されることもありません。
呼び出しスタックハックは、私が調査したPendulumの5つの設計上の決定のうちの1つです。他の4つは whenever のドキュメントにカタログ化されています。
Pythonでさらに呪われた演算子を知っていますか?ぜひ聞かせてください!
-
この投稿のすべては、特に断りがない限り、CPython 3.14でPendulum 3.2.0に対して実行されました。↩
-
夏時間:多くのタイムゾーンでは、時計は春に1時間進み、秋に1時間戻ります。その日、一部の壁時計の時刻はスキップされたり繰り返されたりするため、その日は23時間または25時間になります。↩
-
Java(
java.time)とJavaScript(Temporal、ECMAScript 2026以降)に組み込まれています。Rustでは、Jiffが急速に普及しており、C#ではNodaTimeが標準ライブラリの代替となっています。↩ ↩2 -
どちらの算術処理が「正しい」かは、それ自体が議論の的です。経過時間は最新のdatetimeライブラリでは標準ですが、壁時計の算術処理も一部のコンテキストでは役立つことがあります。↩
-
これは見過ごされていません:#818。正確な遅延はプラットフォームに依存しますが、主に
stat()呼び出しのためです。40マイクロ秒は多いでしょうか?加算はめったに単独で来ません:カレンダー、繰り返しイベント、またはログ行のバケット化を考えてください。それらの1000個はHTTPリクエストと同じくらいの約40ミリ秒かかります。そして、コストは薄く分散されているため、プロファイラでホットスポットとして表示されません。↩ -
この対立は2025年にプロジェクトの現在のメンテナーが引き継ぐ前の2023年12月にリリースされたバージョン3.0で発生しました。3.0より前は、Pendulumは独自のタイムゾーン実装を出荷しており、この問題を回避していました。↩
-
興味深いことに、呼び出しスタックが必要だったとしても、
sys._getframe(1).f_code.co_nameを使用することで、推測をより安価にすることができました。これはtracebackの追加オーバーヘッドなしで呼び出し元の名前を読み取ります。↩ -
DateTimeだけが、ドロップインの約束が変更された挙動と衝突するサブクラスではありません。PendulumのDurationは、.secondsが0から86,399の間にとどまるというtimedeltaの約束を破り、そのTimezoneサブクラスはZoneInfoのキャッシュを逃し、タイムゾーン検索を大幅に遅くします。↩ -
Arrowを含む他のライブラリがこれらの落とし穴にどのように対処しているかについては、私の以前の記事を参照してください。↩