"importlib.resources.abc" -- リソースの抽象基底クラス
*****************************************************

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

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

Added in version 3.11.

class importlib.resources.abc.ResourceReader

   *TraversableResources に取って代わられました*

   *resources* の読み出し機能を提供する *抽象基底クラス (abstract base
   class, ABC)* です。

   この ABC でいう *リソース* は、パッケージに同梱されるバイナリデータ
   です。 通常は、パッケージの "__init__.py" ファイルと同じ場所にある
   データファイルなどを指します。 このクラスの目的は、そのようなデータ
   ファイルへのアクセスを抽象化し、パッケージとデータファイルが zip フ
   ァイル内にあるかファイルシステム上にあるかなどの違いを意識せずに済
   むようにすることです。

   このクラスのどのメソッドでも、*resource* 引数は概念上は単なるファイ
   ル名を表す *path-like object* でなければなりません。 つまり、
   *resource* 引数にサブディレクトリのパスを含めてはいけません。 リー
   ダーが対象とするパッケージの場所が「ディレクトリ」に相当するためで
   す。 この対応関係では、パッケージがディレクトリに、リソースがファイ
   ル名に相当します。 このため、このクラスのインスタンスは特定のパッケ
   ージと直接対応する必要があり、複数のパッケージやモジュールを表すも
   のではありません。

   リソースの読み取りをサポートするローダーは、
   "get_resource_reader(fullname)" というメソッドを提供する必要があり
   ます。 このメソッドは、この ABC のインターフェースを実装するオブジ
   ェクトを返します。 "fullname" で指定されたモジュールがパッケージで
   ない場合は、"None" を返さなければなりません。 指定されたモジュール
   がパッケージである場合にのみ、この ABC と互換性のあるオブジェクトを
   返してください。

   バージョン 3.12 で非推奨: 代わりに
   "importlib.resources.abc.TraversableResources" を使ってください。

   abstractmethod open_resource(resource)

      *resource* をバイナリとして読み取るために開いた *file-like
      object* を返します。

      リソースが見付からない場合は、 "FileNotFoundError" が送出されま
      す。

   abstractmethod resource_path(resource)

      *resource* へのファイルシステムパスを返します。

      リソースの実体がファイルシステムに存在しない場合、
      "FileNotFoundError" が送出されます。

   abstractmethod is_resource(path)

      指定された *path* がリソースとみなされる場合に "True" を返します
      。 *path* が存在しない場合は "FileNotFoundError" を送出します。

      バージョン 3.10 で変更: 引数 *name* の名前を *path* に変更しまし
      た。

   abstractmethod contents()

      パッケージの内容を文字列で返す *iterable* を返します。 イテレー
      タが返す名前がすべて実際のリソースを表す必要はありません。 例え
      ば、"is_resource()" が偽となる名前を返してもかまいません。

      リソース以外の名前も返せるのは、パッケージとそのリソースの格納方
      法があらかじめ分かっていて、そのような名前が役立つ場合に対応する
      ためです。 例えば、パッケージとリソースがファイルシステム上にあ
      ると分かっている場合に直接使えるよう、サブディレクトリ名を返すこ
      とができます。

      この抽象メソッドは、要素を持たないイテラブルを返します。

class importlib.resources.abc.Traversable

   ディレクトリの走査やファイルを開く操作に適した、"pathlib.Path" の一
   部のメソッドを持つオブジェクトです。

   このオブジェクトをファイルシステム上で表すには、
   "importlib.resources.as_file()" を使ってください。

   name

      抽象属性です。 親への参照を含まない、このオブジェクトのベース名
      です。

   abstractmethod iterdir()

      "self" 内の Traversable オブジェクトを yield します。

   abstractmethod is_dir()

      "self" がディレクトリなら "True" を返します。

   abstractmethod is_file()

      "self" がファイルなら "True" を返します。

   abstractmethod joinpath(*pathsegments)

      *pathsegments* に従ってディレクトリをたどり、結果を
      "Traversable" として返します。

      各 *pathsegments* 引数には、スラッシュ ("/"、"posixpath.sep") で
      区切った複数の名前を含められます。 例えば、次の 2 つは等価です。

         files.joinpath('subdir', 'subsuddir', 'file.txt')
         files.joinpath('subdir/subsuddir/file.txt')

      "Traversable" の実装によっては、最新バージョンのプロトコルに更新
      されていない場合があります。 そのような実装との互換性を保つには
      、"joinpath" を呼び出すたびに、パスの区切り文字を含まない引数を
      1 つだけ渡してください。 例えば次のようにします。

         files.joinpath('subdir').joinpath('subsubdir').joinpath('file.txt')

      バージョン 3.11 で変更: "joinpath" は複数の *pathsegments* を受
      け付け、各要素にパスの区切り文字としてスラッシュを含められるよう
      になりました。 以前は *child* 引数を 1 つだけ受け付けていました
      。

   abstractmethod __truediv__(child)

      "self" の子を Traversable として返します。 "joinpath(child)" と
      等価です。

   abstractmethod open(mode='r', *args, **kwargs)

      *mode* に 'r' または 'rb' を指定すると、それぞれテキストまたはバ
      イナリとして開きます。 読み取りに使えるハンドルを返します
      ("pathlib.Path.open" と同じです)。

      テキストとして開く場合、"io.TextIOWrapper" が受け付けるようなエ
      ンコーディングの引数を受け付けます。

   read_bytes()

      "self" の内容をバイト列として読み取ります。

   read_text(encoding=None)

      "self" の内容をテキストとして読み取ります。

class importlib.resources.abc.TraversableResources

   "importlib.resources.files()" インターフェースを提供できるリソース
   リーダーの抽象基底クラスです。 "ResourceReader" を継承し、
   "ResourceReader" の抽象メソッドの具体的な実装を提供します。 そのた
   め、"TraversableResources" を提供するローダーは、"ResourceReader"
   も提供します。

   リソースの読み取りをサポートするローダーは、このインターフェースを
   実装する必要があります。

   abstractmethod files()

      ロードしたパッケージの "importlib.resources.abc.Traversable" オ
      ブジェクトを返します。
