zoneinfo — IANAタイムゾーンサポート—Pythonドキュメント

提供：Dev Guides
< PythonPython/docs/3.9/library/zoneinfo
移動先:案内、検索

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

バージョン3.9の新機能。


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

も参照してください

モジュール： datetime
ZoneInfo クラスが使用されるように設計されている time および datetime タイプを提供します。
パッケージ tzdata
PyPIを介してタイムゾーンデータを提供するためにCPythonコア開発者によって維持されているファーストパーティパッケージ。


ZoneInfoを使用する

ZoneInfo は、 datetime.tzinfo 抽象基本クラスの具体的な実装であり、コンストラクター datetimeを介してtzinfoにアタッチすることを目的としています。 .replace メソッドまたは datetime.astimezone ： 

>>> from zoneinfo import ZoneInfo
>>> from datetime import datetime, timedelta

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

>>> dt.tzname()
'PDT'

この方法で作成された日時は、日時演算と互換性があり、それ以上の介入なしで夏時間の遷移を処理します。 

>>> dt_add = dt + timedelta(days=1)

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

>>> dt_add.tzname()
'PST'

これらのタイムゾーンは、 PEP 495 で導入された fold 属性もサポートします。 あいまいな時間を誘発するオフセット遷移（夏時間から標準時間遷移など）では、遷移の前のからまでのオフセットは、fold=0の場合に使用され、の後のオフセットは[ X212X]トランジションは、fold=1の場合に使用されます。例： 

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

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

別のタイムゾーンから変換する場合、フォールドは正しい値に設定されます。 

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

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

>>> # After the PDT -> PST transition
>>> print((dt_utc + 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（または、より可能性が高いのは[ X243X] フラグ--with-tzpath）。これは os.pathsep で区切られた文字列である必要があります。

すべてのプラットフォームで、構成された値は sysconfig.get_config_var（）のTZPATHキーとして使用できます。


環境構成

TZPATH を初期化するとき（インポート時または reset_tzpath（）が引数なしで呼び出されるとき）、zoneinfoモジュールは環境変数 [X182Xを使用します]（存在する場合）、検索パスを設定します。

PYTHONTZPATH
これは、使用するタイムゾーン検索パスを含む os.pathsep で区切られた文字列です。 相対パスではなく絶対パスのみで構成されている必要があります。 PYTHONTZPATHで指定された相対コンポーネントは使用されませんが、それ以外の場合、相対パスが指定されたときの動作は実装によって定義されます。 CPythonは InvalidTZPathWarning を発生させますが、他の実装はエラーのあるコンポーネントを黙って無視したり、例外を発生させたりすることができます。

システムデータを無視し、代わりにtzdataパッケージを使用するようにシステムを設定するには、PYTHONTZPATH=""を設定します。


ランタイム構成

TZ検索パスは、 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(fobj, /, key=None)

バイトを返すファイルのようなオブジェクトからZoneInfoオブジェクトを構築します（例： バイナリモードで開かれたファイルまたは io.BytesIO オブジェクト）。 プライマリコンストラクタとは異なり、これは常に新しいオブジェクトを構築します。

keyパラメーターは、 __ str __（）および __ repr __（）の目的でゾーンの名前を設定します。

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

classmethod ZoneInfo.no_cache(key)

コンストラクターのキャッシュをバイパスする代替コンストラクター。 これはプライマリコンストラクタと同じですが、呼び出しごとに新しいオブジェクトを返します。 これは、テストまたはデモンストレーションの目的で役立つ可能性が最も高いですが、異なるキャッシュ無効化戦略を使用してシステムを作成するためにも使用できます。

このコンストラクターを介して作成されたオブジェクトは、選択解除されると、逆シリアル化プロセスのキャッシュもバイパスします。

注意

このコンストラクターを使用すると、日時のセマンティクスが驚くべき方法で変更される可能性があります。必要であることがわかっている場合にのみ使用してください。

次のクラスメソッドも使用できます。

classmethod ZoneInfo.clear_cache(*, only_keys=None)

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

反復可能なキー名がonly_keysパラメーターに渡されると、指定されたキーのみがキャッシュから削除されます。 only_keysに渡されたが、キャッシュに見つからなかったキーは無視されます。

警告

この関数を呼び出すと、ZoneInfoを使用して日時のセマンティクスが驚くべき方法で変更される可能性があります。 これにより、プロセス全体のグローバル状態が変更されるため、さまざまな影響が生じる可能性があります。 必要であることがわかっている場合にのみ使用してください。

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

ZoneInfo.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'

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

keyパラメータを指定せずにファイルから構築されたオブジェクトの場合、strは repr（）の呼び出しにフォールバックします。 ZoneInfoのreprは実装定義であり、バージョン間で必ずしも安定しているとは限りませんが、有効なZoneInfoキーではないことが保証されています。


ピクルスのシリアル化

ZoneInfoオブジェクトは、すべての遷移データをシリアル化するのではなく、キーによってシリアル化され、ファイルから構築されたZoneInfoオブジェクト（keyの値が指定されているオブジェクトでも）を選択できません。

ZoneInfoファイルの動作は、ファイルの作成方法によって異なります。

  1. ZoneInfo(key)：プライマリコンストラクタで構築された場合、ZoneInfoオブジェクトはキーによってシリアル化され、逆シリアル化された場合、逆シリアル化プロセスはプライマリを使用するため、これらは同じであると予想されます。同じタイムゾーンへの他の参照としてのオブジェクト。 たとえば、europe_berlin_pklがZoneInfo("Europe/Berlin")から構築されたピクルスを含む文字列である場合、次の動作が予想されます。

    >>> 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")から構築されたピクルスを含む文字列である場合、次の動作が予想されます。

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

  3. ZoneInfo.from_file(fobj, /, key=None)：ファイルから構築された場合、ZoneInfoオブジェクトはpickle化時に例外を発生させます。 エンドユーザーがファイルから構築されたZoneInfoを選択する場合は、ラッパータイプまたはカスタムシリアル化関数を使用することをお勧めします。キーでシリアル化するか、ファイルオブジェクトの内容を保存してシリアル化します。

このシリアル化の方法では、シリアル化と逆シリアル化の両方の環境でクラスと関数への参照が存在すると予想されるのと同様に、必要なキーのタイムゾーンデータがシリアル化と逆シリアル化の両方の側で利用可能である必要があります。 また、タイムゾーンデータのバージョンが異なる環境でピクルス化されたZoneInfoのピクルスを解除した場合、結果の一貫性について保証が行われないことも意味します。


関数

zoneinfo.available_timezones()

タイムゾーンパス上の任意の場所で使用可能なIANAタイムゾーンのすべての有効なキーを含むセットを取得します。 これは、関数を呼び出すたびに再計算されます。

この関数には、正規のゾーン名のみが含まれ、posix/およびright/ディレクトリの下にあるような「特別な」ゾーンやposixrulesゾーンは含まれません。

注意

タイムゾーンパス上のファイルが有効なタイムゾーンであるかどうかを判断する最良の方法は、最初に「マジックストリング」を読み取ることであるため、この関数は多数のファイルを開く可能性があります。

ノート

これらの値は、エンドユーザーに公開されるようには設計されていません。 ユーザー向けの要素の場合、アプリケーションはCLDR（Unicode Common Locale Data Repository）などを使用して、よりユーザーフレンドリーな文字列を取得する必要があります。 ZoneInfo.key の注意事項も参照してください。

zoneinfo.reset_tzpath(to=None)

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

reset_tzpathを呼び出しても、 ZoneInfo キャッシュは無効になりません。したがって、プライマリZoneInfoコンストラクターの呼び出しでは、キャッシュの場合にのみ新しいTZPATHが使用されます。お嬢。

toパラメーターは、文字列の sequence または os.PathLike である必要があり、文字列ではありません。これらはすべて絶対パスである必要があります。 ValueError は、絶対パス以外のものが渡された場合に発生します。


グローバル

zoneinfo.TZPATH

タイムゾーン検索パスを表す読み取り専用シーケンス–キーからZoneInfoを構築する場合、キーはTZPATHの各エントリに結合され、最初に見つかったファイルが使用されます。

TZPATHには、構成方法に関係なく、絶対パスのみを含めることができ、相対パスを含めることはできません。

zoneinfo.TZPATHが指すオブジェクトは、 reset_tzpath（）の呼び出しに応じて変更される可能性があるため、TZPATHをインポートするのではなく、zoneinfo.TZPATHを使用することをお勧めします。 zoneinfoから、またはzoneinfo.TZPATHに長寿命変数を割り当てます。

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


例外と警告

exception zoneinfo.ZoneInfoNotFoundError
指定されたキーがシステムで見つからなかったために ZoneInfo オブジェクトの構築が失敗した場合に発生します。 これは KeyError のサブクラスです。
exception zoneinfo.InvalidTZPathWarning
PYTHONTZPATH に、相対パスなど、除外される無効なコンポーネントが含まれている場合に発生します。



「https://www.finddevguides.com/index.php?title=Python/docs/3.9/library/zoneinfo&oldid=99765」から取得
Powered by MediaWiki