"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)

   >>> # 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 通りの方法で設定できます
。

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)": 通常のコンストラクタで作成した "ZoneInfo" オブジェ
   クトはキーでシリアライズされ、デシリアライズ時も通常のコンストラク
   タが使われます。 そのため、同じタイムゾーンへのほかの参照と同じオブ
   ジェクトになることが期待されます。 例えば、"europe_berlin_pkl" が
   "ZoneInfo("Europe/Berlin")" から作成した pickle のバイト列であれば
   、次の動作が期待されます。

      >>> 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)": ファイルから作成した
   "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" に、相対パスなど除外される無効な要素が含まれる場合に
   発生します。
