zoneinfo --- IANA タイムゾーンのサポート¶
Added in version 3.9.
ソースコード: Lib/zoneinfo
zoneinfo モジュールは、PEP 615 で規定された IANA タイムゾーンデータベースに対応するタイムゾーンの具象実装を提供します。
デフォルトでは、zoneinfo はシステムのタイムゾーンデータが利用できればそれを使います。
利用できない場合は、PyPI で提供される公式の tzdata パッケージを使います。
参考
利用可能な環境: 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)
>>> # PDT から PST への移行前
>>> print(when_utc.astimezone(LOS_ANGELES))
2020-11-01 01:00:00-07:00
>>> # PDT から PST への移行後
>>> 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 通りの方法で設定できます。
実行時 には、
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 を参照）。
ValueErroris 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 の振る舞いは、どのように作成したかによって異なります。
ZoneInfo(key): 通常のコンストラクタで作成したZoneInfoオブジェクトはキーでシリアライズされ、デシリアライズ時も通常のコンストラクタが使われます。 そのため、同じタイムゾーンへのほかの参照と同じオブジェクトになることが期待されます。 例えば、europe_berlin_pklがZoneInfo("Europe/Berlin")から作成した pickle のバイト列であれば、次の動作が期待されます。>>> a = ZoneInfo("Europe/Berlin") >>> b = pickle.loads(europe_berlin_pkl) >>> a is b True
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
ZoneInfo.from_file(file_obj, /, key=None): ファイルから作成したZoneInfoオブジェクトは、ピクル化すると例外を送出します。 ファイルから作成したZoneInfoをピクル化したい場合は、ラッパー型または独自のシリアライズ関数を使うことを推奨します。 キーでシリアライズするか、ファイルオブジェクトの内容を保存してシリアライズします。
このシリアライズ方式では、シリアライズ側とデシリアライズ側の両方で、必要なキーのタイムゾーンデータを利用できなければなりません。
クラスや関数への参照が両方の環境に存在することを期待するのと同様です。
また、異なるバージョンのタイムゾーンデータを持つ環境でピクル化した ZoneInfo をアンピクルする場合、結果の一貫性は保証されません。
関数¶
- zoneinfo.available_timezones()¶
タイムゾーンの検索パス上で利用可能な IANA タイムゾーンの、有効なキーをすべて含む集合を取得します。 関数を呼び出すたびに再計算されます。
この関数は正規のタイムゾーン名だけを含み、
posix/やright/ディレクトリ内のタイムゾーン、posixrules、localtimeなどの特別なタイムゾーンは含みません。注意
タイムゾーンの検索パス上のファイルが有効なタイムゾーンかどうかを判定するには、先頭のマジック文字列を読むのが最適なため、この関数は大量のファイルを開く場合があります。
注釈
これらの値はエンドユーザーへの表示用には設計されていません。 ユーザーに見せる部分では、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に、相対パスなど除外される無効な要素が含まれる場合に発生します。