"importlib.resources" -- パッケージリソースの読み取り、オープン、アクセス
*************************************************************************

**ソースコード:** Lib/importlib/resources/__init__.py

======================================================================

Added in version 3.7.

このモジュールは Python のインポートシステムを利用し、*パッケージ* 内
の *リソース* にアクセスする機能を提供します。

「リソース」は、Python のモジュールやパッケージに関連付けられた、ファ
イルに似たものです。 リソースはパッケージの直下やサブディレクトリ内に
置くことも、パッケージ外のモジュールの隣に置くこともできます。 テキス
トの場合もバイナリの場合もあります。 そのため、パッケージの Python モ
ジュールのソース (.py)、コンパイルで生成されるもの (pycache)、インスト
ールで生成されるもの (ディレクトリ内の "予約済みファイル名" など) も、
技術的にはそのパッケージの事実上のリソースです。 ただし実際には、リソ
ースとは主に、パッケージの作者が明示的に公開する Python コード以外のも
のを指します。

リソースはバイナリモードでもテキストモードでも開いたり読み取ったりでき
ます。

リソースはおおむねディレクトリ内のファイルに似ていますが、これは単なる
比喩である点に注意してください。 リソースとパッケージは、ファイルシス
テム上の物理的なファイルやディレクトリとして存在する必要は **ありませ
ん**。 例えば、"zipimport" を使うとパッケージとそのリソースを zip ファ
イルからインポートできます。

警告:

  "importlib.resources" は組み込みの "open()" 関数と同じセキュリティモ
  デルに従います。 このモジュールの関数に信頼できない入力を渡すことは
  安全ではありません。

注釈:

  このモジュールのスタンドアローンバックポートでは、
  importlib.resources の使用 と pkg_resources から importlib.resources
  への移行 についての詳細情報を提供しています。

"Loaders" でリソースの読み込みをサポートしたい場合は、
"importlib.resources.abc.ResourceReader" で指定された
"get_resource_reader(fullname)" メソッドを実装しなければいけません。

class importlib.resources.Anchor

   リソースの基点 (アンカー) を表します。 "モジュールオブジェクト" ま
   たはモジュール名の文字列です。 "Union[str, ModuleType]" として定義
   されています。

importlib.resources.files(anchor: Anchor | None = None)

   リソースのコンテナ (ディレクトリに相当) とそのリソース (ファイルに
   相当) を表す "Traversable" オブジェクトを返します。 Traversable は
   他のコンテナ (サブディレクトリに相当) を含むこともあります。

   *anchor* は省略可能な "Anchor" です。 パッケージの場合、リソースは
   そのパッケージから解決されます。 モジュールの場合は、そのモジュール
   の隣 (同じパッケージ内またはパッケージのルート) から解決されます。
   省略すると呼び出し元のモジュールが使われます。

   Added in version 3.9.

   バージョン 3.12 で変更: *package* 引数の名前を *anchor* に変更しま
   した。 *package* も引き続き受け付けますが、非推奨となりました。

   バージョン 3.15 で変更: *package* parameter was fully removed.
   *anchor* can now be a non-package module and if omitted will
   default to the caller's module. *package* is no longer accepted
   since Python 3.15. Consider passing the anchor positionally or
   using "importlib_resources >= 5.10" for a compatible interface on
   older Pythons.

importlib.resources.as_file(traversable)

   通常は "importlib.resources.files()" から得られる、ファイルまたはデ
   ィレクトリを表す "Traversable" オブジェクトを受け取り、"with" 文で
   使うコンテキストマネージャを返します。 このコンテキストマネージャは
   "pathlib.Path" オブジェクトを提供します。

   コンテキストマネージャを抜けると、例えば zip ファイルからリソースを
   展開する際に作成した一時ファイルや一時ディレクトリを削除します。

   Traversable のメソッド ("read_text" など) では足りず、ファイルシス
   テム上の実際のファイルやディレクトリが必要な場合は、"as_file" を使
   ってください。

   Added in version 3.9.

   バージョン 3.12 で変更: ディレクトリを表す *traversable* をサポート
   しました。


関数 API
========

簡単に使え、後方互換性のある補助関数が用意されています。 一般的な操作
を 1 回の関数呼び出しで行えます。

以下のすべての関数について、次の規則が適用されます。

* *anchor* は "files()" と同じく "Anchor" です。 "files" と異なり、省
  略できません。

* *path_names* は、基点からの相対パスとして表したリソースのパス名の構
  成要素です。 例えば "info.txt" というリソースのテキストを取得するに
  は、次のようにします。

     importlib.resources.read_text(my_module, "info.txt")

  "Traversable.joinpath" と同じく、各構成要素ではパスの区切り文字にス
  ラッシュ ("/") を使ってください。 例えば、次の 2 つは等価です。

     importlib.resources.read_binary(my_module, "pics/painting.png")
     importlib.resources.read_binary(my_module, "pics", "painting.png")

  後方互換性のため、テキストを読む関数に複数の *path_names* を渡す場合
  は、*encoding* 引数を明示する必要があります。 例えば
  "info/chapter1.txt" のテキストを取得するには、次のようにします。

     importlib.resources.read_text(my_module, "info", "chapter1.txt",
                                   encoding='utf-8')

importlib.resources.open_binary(anchor, *path_names)

   指定した名前のリソースを、バイナリとして読み取るために開きます。

   *anchor* と *path_names* の詳細は 冒頭の説明 を参照してください。

   この関数は "BinaryIO" オブジェクト、つまり読み取り用に開いたバイナ
   リストリームを返します。

   この関数はおおむね次と等価です。

      files(anchor).joinpath(*path_names).open('rb')

   バージョン 3.13 で変更: 複数の *path_names* を指定できるようになり
   ました。

importlib.resources.open_text(anchor, *path_names, encoding='utf-8', errors='strict')

   指定した名前のリソースを、テキストとして読み取るために開きます。 デ
   フォルトでは、内容を厳密な UTF-8 として読み取ります。

   *anchor* と *path_names* の詳細は 冒頭の説明 を参照してください。
   *encoding* と *errors* は組み込みの "open()" と同じ意味です。

   For backward compatibility reasons, the *encoding* argument must be
   given explicitly if there are multiple *path_names*. This
   limitation is scheduled to be removed in Python 3.15.

   この関数は "TextIO" オブジェクト、つまり読み取り用に開いたテキスト
   ストリームを返します。

   この関数はおおむね次と等価です。

      files(anchor).joinpath(*path_names).open('r', encoding=encoding)

   バージョン 3.13 で変更: 複数の *path_names* を指定できるようになり
   ました。 *encoding* と *errors* はキーワード引数で指定する必要があ
   ります。

importlib.resources.read_binary(anchor, *path_names)

   指定した名前のリソースの内容を読み取り、"bytes" として返します。

   *anchor* と *path_names* の詳細は 冒頭の説明 を参照してください。

   この関数はおおむね次と等価です。

      files(anchor).joinpath(*path_names).read_bytes()

   バージョン 3.13 で変更: 複数の *path_names* を指定できるようになり
   ました。

importlib.resources.read_text(anchor, *path_names, encoding='utf-8', errors='strict')

   指定した名前のリソースの内容を読み取り、"str" として返します。 デフ
   ォルトでは、内容を厳密な UTF-8 として読み取ります。

   *anchor* と *path_names* の詳細は 冒頭の説明 を参照してください。
   *encoding* と *errors* は組み込みの "open()" と同じ意味です。

   For backward compatibility reasons, the *encoding* argument must be
   given explicitly if there are multiple *path_names*. This
   limitation is scheduled to be removed in Python 3.15.

   この関数はおおむね次と等価です。

      files(anchor).joinpath(*path_names).read_text(encoding=encoding)

   バージョン 3.13 で変更: 複数の *path_names* を指定できるようになり
   ました。 *encoding* と *errors* はキーワード引数で指定する必要があ
   ります。

importlib.resources.path(anchor, *path_names)

   *resource* へのパスを、実際のファイルシステムパスとして提供します。
   この関数は "with" 文で使うコンテキストマネージャを返します。 このコ
   ンテキストマネージャは "pathlib.Path" オブジェクトを提供します。

   コンテキストマネージャを抜けると、例えば zip ファイルからリソースを
   展開する際に作成した一時ファイルを削除します。

   例えば "stat()" メソッドには実際のファイルシステムパスが必要なので
   、次のように使います。

      with importlib.resources.path(anchor, "resource.txt") as fspath:
          result = fspath.stat()

   *anchor* と *path_names* の詳細は 冒頭の説明 を参照してください。

   この関数はおおむね次と等価です。

      as_file(files(anchor).joinpath(*path_names))

   バージョン 3.13 で変更: 複数の *path_names* を指定できるようになり
   ました。

importlib.resources.is_resource(anchor, *path_names)

   指定した名前のリソースが存在すれば "True"、それ以外は "False" を返
   します。 この関数はディレクトリをリソースとはみなしません。

   *anchor* と *path_names* の詳細は 冒頭の説明 を参照してください。

   この関数はおおむね次と等価です。

      files(anchor).joinpath(*path_names).is_file()

   バージョン 3.13 で変更: 複数の *path_names* を指定できるようになり
   ました。

importlib.resources.contents(anchor, *path_names)

   パッケージまたはパス内の項目の名前を返すイテラブルを返します。 この
   イテラブルは、リソース (ファイルなど) とリソース以外のもの (ディレ
   クトリなど) の名前を "str" で返します。 サブディレクトリ内を再帰的
   にたどることはありません。

   *anchor* と *path_names* の詳細は 冒頭の説明 を参照してください。

   この関数はおおむね次と等価です。

      for resource in files(anchor).joinpath(*path_names).iterdir():
          yield resource.name

   バージョン 3.11 で非推奨: 上記の "iterdir()" を優先して使ってくださ
   い。 結果をより細かく制御でき、機能も豊富です。
