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 オブジェクトを返します。