# `importlib.resources` -- Package resource reading, opening and access

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

バージョン 3.7 で追加.

This module leverages Python's import system to provide access to resources within packages. If you can import a package, you can access resources within that package. Resources can be opened or read, in either binary or text mode.

リソースは大体ディレクトリの中のファイルに似ていますが、これは単なる例え話であることを頭に入れておくことが重要です。例えば、パッケージとそのリソースは `zipimport` を使って zip ファイルからインポートすることができます。

注釈

このモジュールは、 pkg_resources Basic Resource Access に似た機能を、そのパッケージのパフォーマンスのオーバーヘッドを伴わずに提供します。 これにより、パッケージに含まれるリソースの読み込みがより簡単になり、より安定した一貫した意味付けができるようになります。

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

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

class importlib.resources.Package

  Whenever a function accepts a `Package` argument, you can pass in either a `module object` or a module name as a string. You can only pass module objects whose `__spec__.submodule_search_locations` is not `None`.

  The `Package` type is defined as `Union[str, ModuleType]`.

importlib.resources.files(package)

  Returns a `Traversable` object representing the resource container for the package (think directory) and its resources (think files). A Traversable may contain other containers (think subdirectories).

  package is either a name or a module object which conforms to the `Package` requirements.

  バージョン 3.9 で追加.

importlib.resources.as_file(traversable)

  Given a `Traversable` object representing a file, typically from `importlib.resources.files()`, return a context manager for use in a `with` statement. The context manager provides a `pathlib.Path` object.

  Exiting the context manager cleans up any temporary file created when the resource was extracted from e.g. a zip file.

  Use `as_file` when the Traversable methods (`read_text`, etc) are insufficient and an actual file on the file system is required.

  バージョン 3.9 で追加.

## Deprecated functions

An older, deprecated set of functions is still available, but is scheduled for removal in a future version of Python. The main drawback of these functions is that they do not support directories: they assume all resources are located directly within a package.

importlib.resources.Resource

  For resource arguments of the functions below, you can pass in the name of a resource as a string or a `path-like object`.

  The `Resource` type is defined as `Union[str, os.PathLike]`.

importlib.resources.open_binary(package, resource)

  Open for binary reading the resource within package.

  package is either a name or a module object which conforms to the `Package` requirements. resource is the name of the resource to open within package; it may not contain path separators and it may not have sub-resources (i.e. it cannot be a directory). This function returns a `typing.BinaryIO` instance, a binary I/O stream open for reading.

  バージョン 3.11 で非推奨: Calls to this function can be replaced by:

      files(package).joinpath(resource).open('rb')

importlib.resources.open_text(package, resource, encoding='utf-8', errors='strict')

  Open for text reading the resource within package. By default, the resource is opened for reading as UTF-8.

  package is either a name or a module object which conforms to the `Package` requirements. resource is the name of the resource to open within package; it may not contain path separators and it may not have sub-resources (i.e. it cannot be a directory). encoding and errors have the same meaning as with built-in `open()`.

  This function returns a `typing.TextIO` instance, a text I/O stream open for reading.

  バージョン 3.11 で非推奨: Calls to this function can be replaced by:

      files(package).joinpath(resource).open('r', encoding=encoding)

importlib.resources.read_binary(package, resource)

  Read and return the contents of the resource within package as `bytes`.

  package is either a name or a module object which conforms to the `Package` requirements. resource is the name of the resource to open within package; it may not contain path separators and it may not have sub-resources (i.e. it cannot be a directory). This function returns the contents of the resource as `bytes`.

  バージョン 3.11 で非推奨: Calls to this function can be replaced by:

      files(package).joinpath(resource).read_bytes()

importlib.resources.read_text(package, resource, encoding='utf-8', errors='strict')

  Read and return the contents of resource within package as a `str`. By default, the contents are read as strict UTF-8.

  package is either a name or a module object which conforms to the `Package` requirements. resource is the name of the resource to open within package; it may not contain path separators and it may not have sub-resources (i.e. it cannot be a directory). encoding and errors have the same meaning as with built-in `open()`. This function returns the contents of the resource as `str`.

  バージョン 3.11 で非推奨: Calls to this function can be replaced by:

      files(package).joinpath(resource).read_text(encoding=encoding)

importlib.resources.path(package, resource)

  Return the path to the resource as an actual file system path. This function returns a context manager for use in a `with` statement. The context manager provides a `pathlib.Path` object.

  Exiting the context manager cleans up any temporary file created when the resource needs to be extracted from e.g. a zip file.

  package is either a name or a module object which conforms to the `Package` requirements. resource is the name of the resource to open within package; it may not contain path separators and it may not have sub-resources (i.e. it cannot be a directory).

  バージョン 3.11 で非推奨: Calls to this function can be replaced using `as_file()`:

      as_file(files(package).joinpath(resource))

importlib.resources.is_resource(package, name)

  Return `True` if there is a resource named name in the package, otherwise `False`. This function does not consider directories to be resources. package is either a name or a module object which conforms to the `Package` requirements.

  バージョン 3.11 で非推奨: Calls to this function can be replaced by:

      files(package).joinpath(resource).is_file()

importlib.resources.contents(package)

  Return an iterable over the named items within the package. The iterable returns `str` resources (e.g. files) and non-resources (e.g. directories). The iterable does not recurse into subdirectories.

  package is either a name or a module object which conforms to the `Package` requirements.

  バージョン 3.11 で非推奨: Calls to this function can be replaced by:

      (resource.name for resource in files(package).iterdir() if resource.is_file())