zoneinfo --- IANA タイムゾーンのサポート

Added in version 3.9.

ソースコード: Lib/zoneinfo

---

zoneinfo モジュールは PEP 615 で規定された、IANAのタイムゾーンデータベースをサポートした具体的なタイムゾーン実装を提供します。 デフォルトでは、zoneinfo はシステムのタイムゾーンデータが利用可能であれば使用します。システムのタイムゾーンデータが利用できない場合、ライブラリはPyPIにあるファーストパーティーのパッケージ tzdata を代わりに使用します。

参考

モジュール: datetime

ZoneInfo クラスを使用するように設計されたデータ型 time と datetime を提供します。

tzdata パッケージ

CPythonコアデベロッパーによってメンテナンスされているファーストパーティーのパッケージ。タイムゾーンデータを供給し、PyPIで配布されている。

利用可能な環境: not WASI.

このモジュールは WebAssembly では動作しないか、利用不可です。詳しくは、WebAssembly プラットフォーム を見てください。

ZoneInfo を使用する

ZoneInfo は datetime.tzinfo 抽象基底クラスの具象実装であり、tzinfo に指定することを想定しています。 コンストラクタ、datetime.replace メソッド、datetime.astimezone メソッドのいずれかで指定します。

>>> from zoneinfo import ZoneInfo
>>> import datetime as dt

>>> when = dt.datetime(2020, 10, 31, 12, tzinfo=ZoneInfo("America/Los_Angeles"))
>>> print(when)
2020-10-31 12:00:00-07:00

>>> when.tzname()
'PDT'

このように作成した datetime は日時の演算に対応し、追加の処理なしで夏時間への移行や夏時間からの移行を扱えます。

>>> when_add = when + dt.timedelta(days=1)

>>> print(when_add)
2020-11-01 12:00:00-08:00

>>> when_add.tzname()
'PST'

これらのタイムゾーンは PEP 495 で導入された fold 属性もサポートしています。 夏時間から標準時への移行のように、オフセットの変更によって曖昧な時刻が生じる場合、fold=0 では変更 前 のオフセット、fold=1 では変更 後 のオフセットが使われます。 例えば次のようになります。

>>> when = dt.datetime(2020, 11, 1, 1, tzinfo=ZoneInfo("America/Los_Angeles"))
>>> print(when)
2020-11-01 01:00:00-07:00

>>> print(when.replace(fold=1))
2020-11-01 01:00:00-08:00

別のタイムゾーンから変換すると、fold は正しい値に設定されます。

>>> LOS_ANGELES = ZoneInfo("America/Los_Angeles")
>>> when_utc = dt.datetime(2020, 11, 1, 8, tzinfo=dt.timezone.utc)

>>> # Before the PDT -> PST transition
>>> print(when_utc.astimezone(LOS_ANGELES))
2020-11-01 01:00:00-07:00

>>> # After the PDT -> PST transition
>>> print((when_utc + dt.timedelta(hours=1)).astimezone(LOS_ANGELES))
2020-11-01 01:00:00-08:00

データソース

zoneinfo モジュールはタイムゾーンデータを直接提供せず、システムのタイムゾーンデータベース、または利用可能であれば PyPI 上の公式パッケージ tzdata からタイムゾーン情報を取得します。 特に Windows など、一部のシステムでは IANA データベースを利用できません。 そのため、複数のプラットフォームへの対応を目指し、タイムゾーンデータを必要とするプロジェクトでは、tzdata への依存関係を宣言することを推奨します。 システムのデータも tzdata も利用できない場合、ZoneInfo の呼び出しはすべて ZoneInfoNotFoundError を送出します。

データソースの設定

ZoneInfo(key) を呼び出すと、コンストラクタはまず TZPATH で指定されたディレクトリから key に一致するファイルを探し、見つからなければ tzdata パッケージから探します。 この動作は 3 通りの方法で設定できます。

1. ほかに指定がない場合のデフォルトの TZPATH は、コンパイル時 に設定できます。

2. TZPATH は 環境変数 で設定できます。

3. 実行時 には、reset_tzpath() 関数で検索パスを操作できます。

コンパイル時の設定

TZPATH のデフォルト値には、タイムゾーンデータベースが一般に配置される場所がいくつか含まれます (タイムゾーンデータの定番の配置場所がない Windows を除きます)。 POSIX システムでは、システムのタイムゾーンデータの配置場所が分かっている配布者や Python をソースからビルドする人は、コンパイル時のオプション TZPATH (通常は configure フラグ --with-tzpath) を指定してデフォルトのタイムゾーンパスを変更できます。 値は os.pathsep で区切った文字列でなければなりません。

すべてのプラットフォームで、設定された値は sysconfig.get_config_var() に TZPATH キーを渡して取得できます。

環境変数による設定

zoneinfo モジュールは TZPATH を初期化するとき (インポート時や、引数なしで reset_tzpath() が呼び出されるたびに)、環境変数 PYTHONTZPATH があればその値を検索パスの設定に使います。

PYTHONTZPATH

使用するタイムゾーンの検索パスを os.pathsep で区切った文字列です。 相対パスを含めず、絶対パスのみで構成しなければなりません。 PYTHONTZPATH に指定された相対パスの要素は使われませんが、それ以外の動作は実装依存です。 CPython は InvalidTZPathWarning を発生させますが、ほかの実装は不正な要素を黙って無視しても、例外を送出しても構いません。

システムのデータを無視して代わりに tzdata パッケージを使うには、PYTHONTZPATH="" と設定してください。

実行時の設定

タイムゾーンの検索パスは reset_tzpath() 関数で実行時にも設定できます。 通常は推奨されませんが、特定のタイムゾーンパスを使う必要があるテスト関数や、システムのタイムゾーンへのアクセスを無効にする必要があるテスト関数では妥当な使い方です。

ZoneInfo クラス

class zoneinfo.ZoneInfo(key)

文字列 key で指定した IANA タイムゾーンを表す、datetime.tzinfo の具象サブクラスです。 同じキーで通常のコンストラクタを呼び出すと、常に同一のオブジェクトを返します。 言い換えると、ZoneInfo.clear_cache() でキャッシュを無効にしない限り、どの key に対しても次のアサーションは常に成立します。

a = ZoneInfo(key)
b = ZoneInfo(key)
assert a is b

key は上位ディレクトリへの参照を含まない、正規化された POSIX 形式の相対パスでなければなりません。 この形式に従わないキーを渡すと、コンストラクタは ValueError を送出します。

key に一致するファイルが見つからない場合、コンストラクタは ZoneInfoNotFoundError を送出します。

ZoneInfo クラスには2つの別のコンストラクターがあります:

classmethod ZoneInfo.from_file(file_obj, /, key=None)

バイト列を返すファイルライクオブジェクト (バイナリモードで開かれたファイルや io.BytesIO オブジェクトなど) から ZoneInfo オブジェクトを構築します。 通常のコンストラクタとは異なり、常に新しいオブジェクトを構築します。

key 引数は、__str__() と __repr__() で使うタイムゾーンの名前を設定します。

このコンストラクタで生成したオブジェクトはpickle化できません（pickling を参照）。

ValueError is raised if the data read from file_obj is not a valid TZif file.

classmethod ZoneInfo.no_cache(key)

コンストラクタのキャッシュを使わない代替コンストラクタです。 通常のコンストラクタと同じですが、呼び出すたびに新しいオブジェクトを返します。 主にテストやデモに役立ちますが、異なるキャッシュ無効化戦略を持つシステムを作ることもできます。

このコンストラクタで作成したオブジェクトは、アンピクル時にもデシリアライズするプロセスのキャッシュを使いません。

注意

このコンストラクタを使うと、datetime の動作が予想外に変わる場合があります。 必要性が分かっている場合にのみ使ってください。

次のクラスメソッドもサポートされています:

classmethod ZoneInfo.clear_cache(*, only_keys=None)

ZoneInfo クラスのキャッシュを無効にするメソッドです。 引数を渡さない場合はすべてのキャッシュが無効になり、各キーで次に通常のコンストラクタを呼び出すと新しいインスタンスが返されます。

only_keys 引数にキー名のイテラブルを渡すと、指定したキーだけがキャッシュから削除されます。 only_keys に渡したキーがキャッシュにない場合は無視されます。

警告

この関数を呼び出すと、ZoneInfo を使う datetime の動作が予想外に変わる場合があります。 モジュールの状態を変更するため、広範囲に影響する可能性があります。 必要性が分かっている場合にのみ使ってください。

このクラスには属性が 1 つあります。

ZoneInfo.key

コンストラクタに渡した key の値を返す読み取り専用の 属性 です。 key には IANA タイムゾーンデータベースの検索キー (America/New_York、Europe/Paris、Asia/Tokyo など) を指定します。

key 引数を指定せずにファイルから作成したタイムゾーンでは、None になります。

注釈

これらの値をエンドユーザーに表示することは比較的よく行われますが、関連するタイムゾーンを表す主キーとして設計されており、必ずしもユーザーに見せるためのものではありません。 CLDR (Unicode Common Locale Data Repository) などのプロジェクトを使うと、これらのキーからユーザーに分かりやすい文字列を取得できます。

文字列表現

ZoneInfo オブジェクトに str を呼び出したときの文字列表現には、デフォルトでは ZoneInfo.key 属性が使われます (属性のドキュメントにある使用上の注記を参照してください)。

>>> zone = ZoneInfo("Pacific/Kwajalein")
>>> str(zone)
'Pacific/Kwajalein'

>>> when = dt.datetime(2020, 4, 1, 3, 15, tzinfo=zone)
>>> f"{when.isoformat()} [{when.tzinfo}]"
'2020-04-01T03:15:00+12:00 [Pacific/Kwajalein]'

key 引数を指定せずにファイルから作成したオブジェクトでは、str は代わりに repr() を呼び出します。 ZoneInfo の repr の結果は実装依存で、バージョン間で変わらないとは限りませんが、有効な ZoneInfo キーにはならないことが保証されます。

pickle によるシリアライズ

ZoneInfo オブジェクトは、オフセット変更のデータ全体ではなくキーでシリアライズされます。 ファイルから作成した ZoneInfo オブジェクトは、key の値を指定した場合でもピクル化できません。

ZoneInfo の振る舞いは、どのように作成したかによって異なります。

1. ZoneInfo(key): When constructed with the primary constructor, a ZoneInfo object is serialized by key, and when deserialized, the deserializing process uses the primary and thus it is expected that these are the same object as other references to the same time zone. For example, if europe_berlin_pkl is a string containing a pickle constructed from ZoneInfo("Europe/Berlin"), one would expect the following behavior:

   >>> a = ZoneInfo("Europe/Berlin")
   >>> b = pickle.loads(europe_berlin_pkl)
   >>> a is b
   True
   

2. ZoneInfo.no_cache(key): キャッシュを使わないコンストラクタで作成した ZoneInfo オブジェクトもキーでシリアライズされますが、デシリアライズ時にもキャッシュを使わないコンストラクタが使われます。 europe_berlin_pkl_nc が ZoneInfo.no_cache("Europe/Berlin") から作成した pickle のバイト列であれば、次の動作が期待されます。

   >>> a = ZoneInfo("Europe/Berlin")
   >>> b = pickle.loads(europe_berlin_pkl_nc)
   >>> a is b
   False
   

3. ZoneInfo.from_file(file_obj, /, key=None): When constructed from a file, the ZoneInfo object raises an exception on pickling. If an end user wants to pickle a ZoneInfo constructed from a file, it is recommended that they use a wrapper type or a custom serialization function: either serializing by key or storing the contents of the file object and serializing that.

このシリアライズ方式では、シリアライズ側とデシリアライズ側の両方で、必要なキーのタイムゾーンデータを利用できなければなりません。 クラスや関数への参照が両方の環境に存在することを期待するのと同様です。 また、異なるバージョンのタイムゾーンデータを持つ環境でピクル化した ZoneInfo をアンピクルする場合、結果の一貫性は保証されません。

関数

zoneinfo.available_timezones()

タイムゾーンの検索パス上で利用可能な IANA タイムゾーンの、有効なキーをすべて含む集合を取得します。 関数を呼び出すたびに再計算されます。

This function only includes canonical zone names and does not include "special" zones such as those under the posix/ and right/ directories, or the posixrules zone.

注意

タイムゾーンの検索パス上のファイルが有効なタイムゾーンかどうかを判定するには、先頭のマジック文字列を読むのが最適なため、この関数は大量のファイルを開く場合があります。

注釈

これらの値はエンドユーザーへの表示用には設計されていません。 ユーザーに見せる部分では、CLDR (Unicode Common Locale Data Repository) などを使い、より分かりやすい文字列を取得してください。 ZoneInfo.key の注意事項も参照してください。

zoneinfo.reset_tzpath(to=None)

モジュールのタイムゾーン検索パス (TZPATH) を設定またはリセットします。 引数なしで呼び出すと、TZPATH はデフォルト値に設定されます。

reset_tzpath を呼び出しても ZoneInfo のキャッシュは無効になりません。 そのため、通常の ZoneInfo コンストラクタは、キャッシュに対象がない場合にのみ新しい TZPATH を使います。

to 引数は、文字列または os.PathLike からなる シーケンス でなければならず、単一の文字列にはできません。 各要素は絶対パスでなければなりません。 絶対パス以外を渡すと ValueError が送出されます。

グローバル変数

zoneinfo.TZPATH

タイムゾーンの検索パスを表す読み取り専用のシーケンスです。 キーから ZoneInfo を作成するときは、TZPATH の各要素にキーを結合し、最初に見つかったファイルを使います。

TZPATH は、どの方法で設定しても絶対パスのみを含み、相対パスは含みません。

reset_tzpath() の呼び出しによって、zoneinfo.TZPATH が指すオブジェクトは変わる場合があります。 そのため、zoneinfo から TZPATH をインポートしたり、長期間使う変数に zoneinfo.TZPATH の値を代入したりせず、zoneinfo.TZPATH を使うことを推奨します。

タイムゾーン検索パスの設定の詳細は、データソースの設定 を参照してください。

例外と警告

exception zoneinfo.ZoneInfoNotFoundError

指定されたキーがシステム上に見つからず、ZoneInfo オブジェクトの作成に失敗した場合に送出されます。 KeyError のサブクラスです。

exception zoneinfo.InvalidTZPathWarning

PYTHONTZPATH に、相対パスなど除外される無効な要素が含まれる場合に発生します。