テクノロジー · 実用ガイド
Python がタイムゾーンを見つけない？データ不足とキーの誤りを切り分ける
失敗したインタープリターで対照キーと必要なゾーンを比較し、新しいプロセスで配備データを確認します。
例外に UTC と表示されても、UTC を変更すべきとは限りません。まず失敗したプロセスが時刻帯データへアクセスできるか、次に指定キーが存在するかを調べます。
1. 失敗した環境と必要なキーを保存する
完全なトレースバックと、大文字・小文字やアンダースコアを含むキーを保存します。同じ実行ファイル、サービスアカウント、コンテナーまたは仮想環境で診断し、sys.executable、sys.version、zoneinfo.TZPATH、os.environ.get('PYTHONTZPATH') を記録してください。別の対話シェルで動くことは比較材料であり、修復の証明ではありません。
同じ環境で importlib.util.find_spec('tzdata') も確認します。別のインタープリターにはパッケージが見えない場合があります。起動を通すために業務のタイムゾーンを変えたり、時刻帯対応を無効化したり、地域ルールを固定オフセットへ置き換えたりしないでください。
2. 対照キーと必要なキーを比較する
新しいプロセスで ZoneInfo('UTC')、続いて必要な正確なキーを試します。両方失敗する場合はデータの可用性を先に調べます。UTC だけ成功する場合は綴り、配備データセット、そのキーの収録状況を確認します。これは診断の分岐であり、UTC の失敗原因が常に同じという意味ではありません。
対象がニューヨークなら IANA キー America/New_York を確認します。隔離実験では tzdata が利用可能でも America/NewYork と UTC+8 は失敗しました。他の回答から動く都市を適当にコピーすると、過去のオフセットや夏時間の意味が変わるおそれがあります。
3. 配備環境のデータ供給元を証明する
zoneinfo は設定されたシステムディレクトリーを検索し、次に Python の tzdata パッケージを試します。Windows ではパッケージが必要なことが多く、最小 Linux イメージもシステムデータを欠く場合があります。データを担う依存関係を決め、再現可能なアプリやイメージのビルドへ組み込んでください。
パッケージ方式では実際のアプリの Python と承認されたインストーラーを使います。例えばその実行ファイルに -m pip install tzdata を続け、通常の依存マニフェストにも宣言します。管理環境では sudo や回避フラグではなくビルド設定を更新します。システム方式なら OS やイメージの管理者が対応データセットを用意します。
4. 稼働中のキャッシュではなく隔離環境で比較する
Linux の CPython 3.12.14 で四つの子プロセスを試しました。site パッケージを無効にしてシステムパスを残すと UTC と America/New_York は成功しました。さらに PYTHONTZPATH を空にすると失敗し、通常の site 読み込みと空パスではパッケージへのフォールバックで成功しました。相対パスでは InvalidTZPathWarning が出て、この実験では有効なシステムパスが残りませんでした。
パッケージ未導入と、プロセスがデータを見つけられない状態は別です。これは Windows のローカル実験ではありません。空パスは管理されたフォールバック試験に限り、版管理の方針なしに本番へ入れないでください。reset_tzpath は既存の ZoneInfo オブジェクトを消さないため、新規プロセスで検証します。
5. 元の起動経路と季節変化を検証する
最小限の修復後、元の方法で再起動します。必要なキーを変えずに読み込み、元の失敗操作を実行して結果を保存します。地域ゾーンでは代表的な冬夏の日付も期待ルールと比較します。パッケージのみの実験ではニューヨークの 2026 年 1 月 15 日は UTC−05:00、7 月 15 日は UTC−04:00 でした。全歴史データの検証ではありません。
実行ファイル、配備イメージや環境、選んだ依存関係、正確なキー、修復前後の出力を保存します。シェルでは成功してサービスでは失敗するなら、そのサービス内部で同じ情報を採取します。既知のデータがあるのに失敗する場合は名前とデータ版を調べ、都市の当て推量や無関係な環境への再インストールを止めます。
