"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())
