# `importlib` --- `import` の実装

バージョン 3.1 で追加.

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

## はじめに

`importlib` パッケージの目的は2つあります。1つ目は Python ソースコード中にある `import` 文の(そして、拡張として、 `__import__()` 関数の)実装を提供することです。このパッケージは `import` 文の、どの Python インタープリターでも動作する実装を提供します。また、 Python 以外の言語で実装されたどの実装よりも把握しやすい実装を提供します。

2つ目の目的は、このパッケージが公開している `import` を実装するための要素を利用して、(インポーター として知られる) インポートプロセスで動作するカスタムのオブジェクトを実装しやすくすることです。

参考

import 文

  `import` 文の言語リファレンス。

Packages specification

  パッケージの元の仕様。幾つかの動作はこの仕様が書かれた頃から変更されています (例: `sys.modules` で `None` に基づくリダイレクト)。

`__import__()` 関数

  `import` 文はこの関数のシンタックスシュガーです。

PEP 235

  大文字小文字を区別しないプラットフォームでのインポート

PEP 263

  Python のソースコードのエンコーディング

PEP 302

  新しいインポートフック

PEP 328

  複数行のインポートと、絶対/相対インポート

PEP 366

  main モジュールの明示的な相対インポート

PEP 420

  暗黙的な名前空間パッケージ

PEP 451

  インポートシステムのための ModuleSpec 型

PEP 488

  PYO ファイルの撤廃

PEP 489

  複数フェーズでの拡張モジュールの初期化

PEP 552

  決定論的 pyc

PEP 3120

  デフォルトのソースエンコーディングとして UTF-8 を使用

PEP 3147

  PYC リポジトリディレクトリ

## 関数

`importlib.``__import__`(name, globals=None, locals=None, fromlist=(), level=0)

  組み込みの `__import__()` 関数の実装です。

  注釈

  プログラムからモジュールをインポートする場合はこの関数の代わりに `import_module()` を使ってください。

`importlib.``import_module`(name, package=None)

  モジュールをインポートします。name 引数は、インポートするモジュールを絶対または相対表現 (例えば `pkg.mod` または `..mod`) で指定します。name が相対表現で与えられたら、package 引数を、パッケージ名を解決するためのアンカーとなるパッケージの名前に設定する必要があります (例えば `import_module('..mod', 'pkg.subpkg')` は `pkg.mod` をインポートします)。

  `import_module()` 関数は `importlib.__import__()` を単純化するラッパーとして働きます。つまり、この関数のすべての意味は `importlib.__import__()` から受け継いでいます。これらの2つの関数の最も重要な違いは、 `import_module()` が指定されたパッケージやモジュール (例えば `pkg.mod`) を返すのに対し、 `__import__()` はトップレベルのパッケージやモジュール (例えば `pkg`) を返すことです。

  もしモジュールを動的にインポートしていて、インタープリタの実行開始後にモジュールが作成された (例えば、 Python ソースファイルを作成した) 場合、インポートシステムが新しいモジュールを見つけられるように、 `invalidate_caches()` を呼ぶ必要があるでしょう。

  バージョン 3.3 で変更: 親パッケージは自動的にインポートされます。

`importlib.``find_loader`(name, path=None)

  モジュールのローダーを、オプションで指定された path 内から、検索します。モジュールが `sys.modules` にあれば、 `sys.modules[name].__loader__` が返されます (ただしローダーが `None` であるか設定されていなければ `ValueError` が送出されます)。なければ、 `sys.meta_path` を使った検索がなされます。ローダーが見つからなければ `None` が返ります。

  ドットのついた名前表記は、親モジュールのロードが必要なときに暗黙にインポートしないので、望ましくありません。 サブモジュールを適切にインポートするには、そのサブモジュールの全ての親パッケージをインポートし、 path に正しい引数を使ってください。

  バージョン 3.3 で追加.

  バージョン 3.4 で変更: `__loader__` が set でない場合、`None` に設定されているときと同様に `ValueError` を送出します。

  バージョン 3.4 で非推奨: 代わりに `importlib.util.find_spec()` を使用してください。

`importlib.``invalidate_caches`()

  `sys.meta_path` に保存されたファインダーの内部キャッシュを無効にします。ファインダーが `invalidate_caches()` を実装していれば、無効化を行うためにそれが呼び出されます。すべてのファインダーが新しいモジュールの存在に気づくことを保証しているプログラムの実行中に、モジュールが作成またはインストールされたなら、この関数が呼び出されるべきです。

  バージョン 3.3 で追加.

`importlib.``reload`(module)

  以前にインポートされた module をリロードします。引数はモジュールオブジェクトでなければならず、したがってそれ以前に必ずインポートに成功していなければなりません。この関数は、モジュールのソースファイルを外部エディタで編集していて Python インタープリタから離れることなく新しいバージョンを試したい際に便利です。戻り値はモジュールオブジェクトです。 (もし再インポートが異なるオブジェクトを `sys.modules` に配置したら、元の module とは異なるかもしれません。)

  `reload()` が実行された場合:

  - Python モジュールのコードは再コンパイルされ、モジュールレベルのコードが再度実行されます。モジュールの辞書中にある何らかの名前に結び付けられたオブジェクトは、そのモジュールを最初にロードしたときの ローダー を再利用して新たに定義されます。拡張モジュールの `init` 関数が二度呼び出されることはありません。

  - Python における他のオブジェクトと同様、以前のオブジェクトのメモリ領域は、参照カウントがゼロにならないかぎり再利用されません。

  - モジュール名前空間内の名前は新しいオブジェクト (または更新されたオブジェクト) を指すよう更新されます。

  - 以前のオブジェクトが (外部の他のモジュールなどからの) 参照を受けている場合、それらを新たなオブジェクトに再束縛し直すことはないので、必要なら自分で名前空間を更新しなければなりません。

  いくつか補足説明があります:

  モジュールが再ロードされた際、その辞書 (モジュールのグローバル変数を含みます) はそのまま残ります。名前の再定義を行うと、以前の定義を上書きするので、一般的には問題はありません。新たなバージョンのモジュールが古いバージョンで定義された名前を定義していない場合、古い定義がそのまま残ります。辞書がグローバルテーブルやオブジェクトのキャッシュを維持していれば、この機能をモジュールを有効性を引き出すために使うことができます --- つまり、 `try` 文を使えば、必要に応じてテーブルがあるかどうかをテストし、その初期化を飛ばすことができます:

      try:
          cache
      except NameError:
          cache = {}

  組み込みモジュールや動的にロードされるモジュールを再ロードすることは、一般的にそれほど便利ではありません。 `sys`, `__main__`, `builtins` やその他重要なモジュールの再ロードはお勧め出来ません。多くの場合、拡張モジュールは 1 度以上初期化されるようには設計されておらず、再ロードされた場合には何らかの理由で失敗するかもしれません。

  一方のモジュールが `from` ... `import` ... を使って、オブジェクトを他方のモジュールからインポートしているなら、他方のモジュールを `reload()` で呼び出しても、そのモジュールからインポートされたオブジェクトを再定義することはできません --- この問題を回避する一つの方法は、 `from` 文を再度実行することで、もう一つの方法は `from` 文の代わりに `import` と限定的な名前 (module.name) を使うことです。

  あるモジュールがクラスのインスタンスを生成している場合、そのクラスを定義しているモジュールの再ロードはそれらインスタンスのメソッド定義に影響しません --- それらは古いクラス定義を使い続けます。これは派生クラスの場合でも同じです。

  バージョン 3.4 で追加.

  バージョン 3.7 で変更: リロードされたモジュールの `ModuleSpec` が欠けていたときは `ModuleNotFoundError` が送出されます。

## `importlib.abc` -- インポートに関連する抽象基底クラス

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

`importlib.abc` モジュールは、 `import` に使われるすべてのコア抽象基底クラス含みます。コア抽象基底クラスの実装を助けるために、コア抽象基底クラスのサブクラスもいくつか提供されています。

抽象基底クラス階層:

    object
     +-- Finder (deprecated)
     +-- MetaPathFinder
     +-- PathEntryFinder
     +-- Loader
          +-- ResourceLoader --------+
          +-- InspectLoader          |
               +-- ExecutionLoader --+
                                     +-- FileLoader
                                     +-- SourceLoader

class `importlib.abc.``Finder`

  finder を表す抽象基底クラスです。

  バージョン 3.3 で非推奨: 代わりに `MetaPathFinder` または `PathEntryFinder` を使ってください。

  abstractmethod `find_module`(fullname, path=None)

    指定されたモジュールの ローダー を検索するための抽象メソッドです。もとは PEP 302 で仕様が定められ、このメソッドは `sys.meta_path` の中およびパスに基づくインポートサブシステムの中で使用することを意図されています。

    バージョン 3.4 で変更: 呼び出されたときに `NotImplementedError` を送出する代わりに `None` を返します。

    バージョン 3.10 で非推奨: Implement `MetaPathFinder.find_spec()` or `PathEntryFinder.find_spec()` instead.

class `importlib.abc.``MetaPathFinder`

  meta path finder を表す抽象基底クラスです。

  バージョン 3.3 で追加.

  バージョン 3.10 で変更: `Finder` のサブクラスではなくなりました。

  `find_spec`(fullname, path, target=None)

    指定されたモジュールに対応する スペック を検索する抽象メソッド。もしこれがトップレベルのインポートなら、 path は `None` です。そうでなければ、これはサブパッケージまたはモジュールのための検索で、 path は親パッケージの `__path__` の値です。スペックが見つからなければ `None` が返されます。 `target` は、渡されてきたならモジュールオブジェクトです。これはファインダーがどのようなスペックを返せばよいか推測するために使用します。具体的な `MetaPathFinders` を実装するためには `importlib.util.spec_from_loader()` が便利かもしれません。

    バージョン 3.4 で追加.

  `find_module`(fullname, path)

    指定されたモジュールの ローダー を検索するためのレガシーなメソッドです。これがトップレベルのインポートなら、 path は `None` になります。そうでなければ、これはサブパッケージまたはモジュールの検索で、 path は親パッケージの `__path__` の値になります。ローダーが見つからなければ、 `None` が返されます。

    `find_spec()` が定義された場合、後方互換な機能が提供されます。

    バージョン 3.4 で変更: このメソッドが呼ばれた場合 `NotImplementedError` を投げる代わりに `None` を返します。この機能を提供するのに `find_spec()` を使用できます。

    バージョン 3.4 で非推奨: 代わりに `find_spec()` を使用してください。

  `invalidate_caches`()

    このファインダーで使われている内部キャッシュがあれば無効にするオプションのメソッドです。 `sys.meta_path` 上のすべてのファインダーのキャッシュを無効化する際、 `importlib.invalidate_caches()` によって使われます。

    バージョン 3.4 で変更: 呼び出されたときに `NotImplemented` を送出する代わりに `None` を返します。

class `importlib.abc.``PathEntryFinder`

  path entry finder を表す抽象基底クラスです。 `MetaPathFinder` と似ているところがありますが、 `PathEntryFinder` は `importlib.machinery.PathFinder` が提供するパスに基づく import サブシステムの中でのみ使うことが意図されています。

  バージョン 3.3 で追加.

  バージョン 3.10 で変更: `Finder` のサブクラスではなくなりました。

  `find_spec`(fullname, target=None)

    指定されたモジュールに対応する スペック を検索する抽象メソッド。ファインダーは、割り当てられている パス・エントリー 内のモジュールだけを検索します。スペックが見つからなければ `None` が返されます。 `target` は、渡されてきたならモジュールオブジェクトです。これはファインダーがどのようなスペックを返せばよいか推測するために使用します。具体的な `PathEntryFinders` を実装するためには `importlib.util.spec_from_loader()` が便利かもしれません。

    バージョン 3.4 で追加.

  `find_loader`(fullname)

    指定されたモジュールの ローダー を検索する抽象メソッドです。 `(loader, portion)` の 2-タプルを返します。ただし `portion` は名前空間パッケージの部分に寄与するファイルシステム上の場所のシーケンスです。 loader は名前空間パッケージへのファイルシステム上の場所の寄与を表す `portion` を明記するとき `None` にできます。loader が名前空間パッケージの一部ではないことを明記するとき `portion` に空のリストが使えます。 `loader` が `None` で `portion` が空のリストなら、名前空間パッケージのローダーや場所が見つかりませんでした (すなわち、モジュールの何も見つかりませんでした)。

    `find_spec()` が定義された場合、後方互換な機能が提供されます。

    バージョン 3.4 で変更: `NotImplementedError` を送出する代わりに `(None, [])` を返します。機能を提供できる場合 `find_spec()` を使用します。

    バージョン 3.4 で非推奨: 代わりに `find_spec()` を使用してください。

  `find_module`(fullname)

    `Finder.find_module()` の具象実装で、 `self.find_loader(fullname)[0]` と等価です。

    バージョン 3.4 で非推奨: 代わりに `find_spec()` を使用してください。

  `invalidate_caches`()

    このファインダーで使われている内部キャッシュがあれば無効にするオプションのメソッドです。キャッシュされたすべてのファインダーの無効化する際、 `importlib.machinery.PathFinder.invalidate_caches()` によって使われます。

class `importlib.abc.``Loader`

  loader の抽象基底クラスです。ローダーの厳密な定義は PEP 302 を参照してください。

  リソースの読み出しをサポートさせたいローダーには、 `importlib.abc.ResourceReader` で指定されている `get_resource_reader(fullname)` を実装してください。

  バージョン 3.7 で変更: オプションの `get_resource_reader()` メソッドが導入されました。

  `create_module`(spec)

    モジュールをインポートする際に使用されるモジュールオブジェクトを返すメソッド。このメソッドは `None` を戻すことができ、その場合はデフォルトのモジュール作成のセマンティクスが適用されることを示します。

    バージョン 3.4 で追加.

    バージョン 3.5 で変更: Python 3.6 からは、 `exec_module()` が定義されている場合は、このメソッドはオプションではなくなります。

  `exec_module`(module)

    モジュールがインポートまたはリロードされる際に、そのモジュールをモジュール自身の名前空間の中で実行する抽象的なメソッド。 `exec_module()` が呼ばれる時点で、モジュールはすでに初期設定されている必要があります。 このメソッドが存在するときは、 `create_module()` の定義が必須です。

    バージョン 3.4 で追加.

    バージョン 3.6 で変更: `create_module()` の定義が必須となりました。

  `load_module`(fullname)

    モジュールをロードするためのレガシーなメソッドです。モジュールがロードできなければ `ImportError` を送出し、ロードできればロードされたモジュールを返します。

    要求されたモジュールが既に `sys.modules` に存在したなら、そのモジュールが使われリロードされる必要があります。存在しなければ、インポートからの再帰を防ぐため、ローダーはロードが始まる前に新しいモジュールを作成して `sys.modules` に挿入する必要があります。ローダーがモジュールを挿入した後にロードが失敗したなら、ローダーはそのモジュールを `sys.modules` から削除する必要があります。ローダーが実行を始める前に既に `sys.modules` にあったモジュールは、そのままにします (`importlib.util.module_for_loader()` を参照してください)。

    ローダーはモジュールにいくつかの属性を設定する必要があります。(なお、これらの属性には、モジュールがリロードされた際に変化するものがあります):

    - `__name__`

        モジュールの名前です。

    - `__file__`

        モジュールのデータが保存されている場所へのパスです (組み込みモジュールには設定されません)。

    - `__cached__`

        モジュールのコンパイルされた版が保存されている (べき) 場所へのパスです (この属性が適切でないときには設定されません)。

    - `__path__`

        パッケージ内の検索パスを指定する文字列のリストです。この属性はモジュールには設定されません。

    - `__package__`

        The fully qualified name of the package under which the module was loaded as a submodule (or the empty string for top-level modules). For packages, it is the same as `__name__`. The `importlib.util.module_for_loader()` decorator can handle the details for `__package__`.

    - `__loader__`

        モジュールをロードするのに使われたローダーです。 `importlib.util.module_for_loader()` デコレータで、 `__package__` の詳細を扱えます。

    `exec_module()` が利用可能な場合、後方互換な機能が提供されます。

    バージョン 3.4 で変更: このメソッドが呼ばれた時に、 `NotImplementedError` の代わりに `ImportError` を送出します。 `exec_module()` が利用可能な時は、この機能は提供されます。

    バージョン 3.4 で非推奨: モジュールをロードするための推奨される API は、 `exec_module()` (および `create_module()`) です。ローダーは load_module() の代わりにそれを実装するべきです。 exec_module() が実装されている場合、インポート機構は load_module() の他のすべての責任を肩代わりします。

  `module_repr`(module)

    実装されていた場合、与えられたモジュールの repr を計算して文字列として返すためのレガシーなメソッドです。モジュール型のデフォルトの repr() は、必要に応じてこのメソッドの結果を使います。

    バージョン 3.3 で追加.

    バージョン 3.4 で変更: 抽象メソッドではなくオプショナルになりました。

    バージョン 3.4 で非推奨: インポート機構はこれを自動的に考慮するようになりました。

class `importlib.abc.``ResourceReader`

  Superseded by TraversableResources

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

  From the perspective of this ABC, a resource is a binary artifact that is shipped within a package. Typically this is something like a data file that lives next to the `__init__.py` file of the package. The purpose of this class is to help abstract out the accessing of such data files so that it does not matter if the package and its data file(s) are stored in a e.g. zip file versus on the file system.

  For any of methods of this class, a resource argument is expected to be a path-like object which represents conceptually just a file name. This means that no subdirectory paths should be included in the resource argument. This is because the location of the package the reader is for, acts as the "directory". Hence the metaphor for directories and file names is packages and resources, respectively. This is also why instances of this class are expected to directly correlate to a specific package (instead of potentially representing multiple packages or a module).

  Loaders that wish to support resource reading are expected to provide a method called `get_resource_reader(fullname)` which returns an object implementing this ABC's interface. If the module specified by fullname is not a package, this method should return `None`. An object compatible with this ABC should only be returned when the specified module is a package.

  バージョン 3.7 で追加.

  abstractmethod `open_resource`(resource)

    Returns an opened, file-like object for binary reading of the resource.

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

  abstractmethod `resource_path`(resource)

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

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

  abstractmethod `is_resource`(name)

    name という名前がリソースだと見なせるなら `True` を返します。 name が存在しない場合は `FileNotFoundError` が送出されます。

  abstractmethod `contents`()

    Returns an iterable of strings over the contents of the package. Do note that it is not required that all names returned by the iterator be actual resources, e.g. it is acceptable to return names for which `is_resource()` would be false.

    Allowing non-resource names to be returned is to allow for situations where how a package and its resources are stored are known a priori and the non-resource names would be useful. For instance, returning subdirectory names is allowed so that when it is known that the package and resources are stored on the file system then those subdirectory names can be used directly.

    The abstract method returns an iterable of no items.

class `importlib.abc.``ResourceLoader`

  loader の抽象基底クラスで、ストレージバックエンドから任意のリソースをロードするオプションの PEP 302 プロトコルを実装します。

  バージョン 3.7 で非推奨: This ABC is deprecated in favour of supporting resource loading through `importlib.abc.ResourceReader`.

  abstractmethod `get_data`(path)

    path に割り当てられたデータのバイト列を返す抽象メソッドです。任意のデータを保管できるファイル的なストレージバックエンドをもつローダーは、この抽象メソッドを実装して、保管されたデータに直接アクセスさせるようにできます。 path が見つからなければ `OSError` を送出する必要があります。 path は、モジュールの `__file__` 属性を使って、またはパッケージの `__path__` の要素を使って、構成されることが期待されます。

    バージョン 3.4 で変更: `NotImplementedError` の代わりに `OSError` を送出します。

class `importlib.abc.``InspectLoader`

  loader の抽象基底クラスで、ローダーがモジュールを検査するためのオプションの PEP 302 プロトコルを実装します。

  `get_code`(fullname)

    モジュールの `code` オブジェクトを返すか、 (例えば組み込みモジュールの場合に) モジュールがコードオブジェクトを持たなければ `None` を返します。要求されたモジュールをローダーが見つけられなかった場合は `ImportError` を送出します。

    注釈

    このメソッドにはデフォルト実装がありますが、とはいえパフォーマンスのために、可能ならばオーバライドしたほうが良いです。

    バージョン 3.4 で変更: このメソッドはもはや抽象メソッドではなく、具象実装が提供されます。

  abstractmethod `get_source`(fullname)

    モジュールのソースを返す抽象メソッドです。これは認識されたすべての行セパレータを `'\n'` 文字に変換し、 universal newlines を使ったテキスト文字列として返されます。利用できるソースがなければ (例えば組み込みモジュール)、 `None` を返します。指定されたモジュールが見つからなければ、 `ImportError` を送出します。

    バージョン 3.4 で変更: `NotImplementedError` の代わりに `ImportError` を送出します。

  `is_package`(fullname)

    モジュールがパッケージであれば True を返し、そうでなければ False を返すオプションのメソッドです。 ローダー がモジュールを見つけられなかったなら `ImportError` が送出されます。

    バージョン 3.4 で変更: `NotImplementedError` の代わりに `ImportError` を送出します。

  static `source_to_code`(data, path='<string>')

    Python のソースからコードオブジェクトを作ります。

    data 引数は `compile()` 関数がサポートするもの (すなわち文字列かバイト) なら何でも構いません。path 引数はソースコードの元々の場所への "パス" でなければなりませんが、抽象概念 (例えば zip ファイル内の場所) でも構いません。

    結果のコードオブジェクトを使って、 `exec(code, module.__dict__)` を呼ぶことでモジュール内でコードを実行できます。

    バージョン 3.4 で追加.

    バージョン 3.5 で変更: スタティックメソッドになりました。

  `exec_module`(module)

    `Loader.exec_module()` の実装です。

    バージョン 3.4 で追加.

  `load_module`(fullname)

    `Loader.load_module()` の実装です。

    バージョン 3.4 で非推奨: 代わりに `exec_module()` を使用してください。

class `importlib.abc.``ExecutionLoader`

  `InspectLoader` から継承された抽象基底クラスで、実装されていれば、モジュールをスクリプトとして実行する助けになります。この抽象基底クラスはオプションの PEP 302 プロトコルを表します。

  abstractmethod `get_filename`(fullname)

    指定されたモジュールの `__file__` の値を返す抽象メソッドです。利用できるパスがなければ、 `ImportError` が送出されます。

    ソースコードが利用できるなら、そのモジュールのロードにバイトコードが使われたかにかかわらず、このメソッドはそのソースファイルへのパスを返す必要があります。

    バージョン 3.4 で変更: `NotImplementedError` の代わりに `ImportError` を送出します。

class `importlib.abc.``FileLoader`(fullname, path)

  `ResourceLoader` と `ExecutionLoader` から継承された抽象基底クラスで、 `ResourceLoader.get_data()` および `ExecutionLoader.get_filename()` の具象実装を提供します。

  fullname 引数は、ローダーが解決しようとするモジュールの、完全に解決された名前です。path 引数は、モジュールのファイルへのパスです。

  バージョン 3.3 で追加.

  `name`

    ローダーが扱えるモジュールの名前です。

  `path`

    モジュールのファイルへのパスです。

  `load_module`(fullname)

    親クラスの `load_module()` を呼び出します。

    バージョン 3.4 で非推奨: 代わりに `Loader.exec_module()` を使用してください。

  abstractmethod `get_filename`(fullname)

    `path` を返します。

  abstractmethod `get_data`(path)

    path をバイナリファイルとして読み込み、そのバイト列を返します。

class `importlib.abc.``SourceLoader`

  ソース (オプションでバイトコード) ファイルのロードを実装する抽象基底クラスです。このクラスは、 `ResourceLoader` と `ExecutionLoader` の両方を継承し、以下の実装が必要です:

  - `ResourceLoader.get_data()`

  - `ExecutionLoader.get_filename()`

      ソースファイルへのパスのみを返す必要があります。ソースなしのロードはサポートされていません。

  このクラスでこれらの抽象メソッドを定義することで、バイトコードファイルを追加でサポートします。これらのメソッドを定義しなければ (またはそのモジュールが `NotImplementedError` を送出すれば)、このローダーはソースコードに対してのみ働きます。これらのメソッドを実装することで、ローダーはソースとバイトコードファイル の組み合わせ に対して働きます。バイトコードのみを与えた ソースのない ロードは認められません。バイトコードファイルは、 Python コンパイラによる解析の工程をなくして速度を上げる最適化です。ですから、バイトコード特有の API は公開されていません。

  `path_stats`(path)

    指定されたパスについてのメタデータを含む `dict` を返す、オプションの抽象メソッドです。サポートされる辞書のキーは:

    - `'mtime'` (必須): ソースコードの更新時刻を表す整数または浮動小数点数です。

    - `'size'` (任意): バイト数で表したソースコードのサイズです。

    未来の拡張のため、辞書内の他のキーは無視されます。パスが扱えなければ、 `OSError` が送出されます。

    バージョン 3.3 で追加.

    バージョン 3.4 で変更: `NotImplementedError` の代わりに `OSError` を送出します。

  `path_mtime`(path)

    指定されたパスの更新時刻を返す、オプションの抽象メソッドです。

    バージョン 3.3 で非推奨: このメソッドは廃止され、 `path_stats()` が推奨されます。このモジュールを実装する必要はありませんが、互換性のため現在も利用できます。パスが扱えなければ、 `OSError` が送出されます。

    バージョン 3.4 で変更: `NotImplementedError` の代わりに `OSError` を送出します。

  `set_data`(path, data)

    ファイルパスに指定されたバイト列を書き込むオプションの抽象メソッドです。存在しない中間ディレクトリがあれば、自動で作成されます。

    パスへの書き込みが読み出し専用のために失敗したとき (`errno.EACCES`/`PermissionError`) 、その例外を伝播させません。

    バージョン 3.4 で変更: 呼ばれたときに `NotImplementedError` を送出することは最早ありません。

  `get_code`(fullname)

    `InspectLoader.get_code()` の具象実装です。

  `exec_module`(module)

    `Loader.exec_module()` の具象実装です。

    バージョン 3.4 で追加.

  `load_module`(fullname)

    `Loader.load_module()` の具象実装です。

    バージョン 3.4 で非推奨: 代わりに `exec_module()` を使用してください。

  `get_source`(fullname)

    `InspectLoader.get_source()` の具象実装です。

  `is_package`(fullname)

    `InspectLoader.is_package()` の具象実装です。モジュールは、次の 両方 を満たすならパッケージであると決定されます。モジュールの (`ExecutionLoader.get_filename()` で与えられる) ファイルパスが、ファイル拡張子を除くと `__init__` という名のファイルであること。モジュール名自体が `__init__` で終わらないこと。

class `importlib.abc.``Traversable`

  An object with a subset of `pathlib.Path` methods suitable for traversing directories and opening files.

  For a representation of the object on the file-system, use `importlib.resources.as_file()`.

  バージョン 3.9 で追加.

  abstractmethod `name`()

    The base name of this object without any parent references.

  abstractmethod `iterdir`()

    Yield Traversable objects in self.

  abstractmethod `is_dir`()

    Return True if self is a directory.

  abstractmethod `is_file`()

    Return True if self is a file.

  abstractmethod `joinpath`(child)

    Return Traversable child in self.

  abstractmethod `__truediv__`(child)

    Return Traversable child in self.

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

    mode may be 'r' or 'rb' to open as text or binary. Return a handle suitable for reading (same as `pathlib.Path.open`).

    When opening as text, accepts encoding parameters such as those accepted by `io.TextIOWrapper`.

  `read_bytes`()

    Read contents of self as bytes.

  `read_text`(encoding=None)

    Read contents of self as text.

  Note: In Python 3.11 and later, this class is found in `importlib.resources.abc`.

class `importlib.abc.``TraversableResources`

  An abstract base class for resource readers capable of serving the `files` interface. Subclasses ResourceReader and provides concrete implementations of the ResourceReader's abstract methods. Therefore, any loader supplying TraversableResources also supplies ResourceReader.

  Loaders that wish to support resource reading are expected to implement this interface.

  バージョン 3.9 で追加.

  Note: In Python 3.11 and later, this class is found in `importlib.resources.abc`.

## `importlib.resources` -- リソース

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

バージョン 3.7 で追加.

このモジュールは、Pythonのインポートシステムを利用して、 パッケージ 内の リソース へのアクセスを提供します。パッケージをインポートすることができれば、そのパッケージ内のリソースにアクセスすることができます。リソースは、バイナリモードでもテキストモードでも、開いたり読んだりすることができます。

Resources are roughly akin to files inside directories, though it's important to keep in mind that this is just a metaphor. Resources and packages do not have to exist as physical files and directories on the file system.

注釈

This module provides functionality similar to pkg_resources Basic Resource Access without the performance overhead of that package. This makes reading resources included in packages easier, with more stable and consistent semantics.

The standalone backport of this module provides more information on using importlib.resources and migrating from pkg_resources to importlib.resources.

リソースの読み出しをサポートさせたいローダーには、 `importlib.abc.ResourceReader` で指定されている `get_resource_reader(fullname)` を実装してください。

次の型が定義されています。

`importlib.resources.``Package`

  The `Package` type is defined as `Union[str, ModuleType]`. This means that where the function describes accepting a `Package`, you can pass in either a string or a module. Module objects must have a resolvable `__spec__.submodule_search_locations` that is not `None`.

`importlib.resources.``Resource`

  This type describes the resource names passed into the various functions in this package. This is defined as `Union[str, os.PathLike]`.

次の関数が利用可能です。

`importlib.resources.``files`(package)

  Returns an `importlib.abc.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 は、名前または `Package` の要件に適合するモジュールオブジェクトのいずれかです。

  バージョン 3.9 で追加.

`importlib.resources.``as_file`(traversable)

  Given a `importlib.abc.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.

  コンテキストマネージャを終了すると、例えば zip ファイルからリソースを抽出した際に作成された一時ファイルが消去されます。

  Traversable のメソッド( `read_text` など)では不十分で、ファイルシステム上の実際のファイルが必要な場合には、 `as_file` を使用します。

  バージョン 3.9 で追加.

`importlib.resources.``open_binary`(package, resource)

  パッケージ 内の リソース をバイナリ読み取り用に開きます。

  package は `Package` の要件に従った名前またはモジュールオブジェクトです。 resource は package 内で開くリソースの名前です。パス区切り文字を含むことはできず、サブリソースを持つことはできません（つまり、ディレクトリにはなれません）。 この関数は、バイナリI/Oストリームを読み込むために開いている `typing.BinaryIO` のインスタンスを返します。

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

  package 内の resource をテキスト読み取り用に開きます。 デフォルトでは、リソースはUTF-8として読み取り用に開かれます。

  package は `Package` の要件に従った名前またはモジュールオブジェクトです。 resource は package 内で開くリソースの名前です。パス区切り文字を含むことはできず、サブリソースを持つことはできません（つまり、ディレクトリにはなれません）。 encoding と errors は、組み込みの `open()` と同じ意味を持ちます。

  この関数は、テキストI/Oストリームを読み込むために開いている `typing.TextIO` のインスタンスを返します。

`importlib.resources.``read_binary`(package, resource)

  package 内の resource の内容を読み取り、 `bytes` として返します。

  package は `Package` の要件に従った名前またはモジュールオブジェクトです。 resource は package 内で開くリソースの名前です。パス区切り文字を含むことはできず、サブリソースを持つことはできません（つまり、ディレクトリにはなれません）。この関数は、リソースの内容を `bytes` として返します。

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

  package 内の resource の内容を読み込んで `str` として返します。デフォルトでは、内容は厳密なUTF-8として読み込まれます。

  package は `Package` の要件に従った名前またはモジュールオブジェクトです。 resource は package 内で開くリソースの名前です。パス区切り文字を含むことはできず、サブリソースを持つことはできません（つまり、ディレクトリにはなれません）。 encoding と errors は、組み込みの `open()` と同じ意味を持ちます。この関数は、リソースの内容を `str` として返します。

`importlib.resources.``path`(package, resource)

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

  コンテキストマネージャーを終了すると、例えば zip ファイルからリソースを抽出する必要がある場合に作成される一時ファイルを削除します。

  package は `Package` の要件に従った名前またはモジュールオブジェクトです。 resource は package 内で開くリソースの名前です。パス区切り文字を含むことはできず、サブリソースを持つことはできません（つまり、ディレクトリにはなれません）。

`importlib.resources.``is_resource`(package, name)

  Return `True` if there is a resource named name in the package, otherwise `False`. Remember that directories are not resources! package is either a name or a module object which conforms to the `Package` requirements.

`importlib.resources.``contents`(package)

  パッケージ内の名前付きアイテムに対するイテラブルを返します。 イテラブルは `str` リソース(ファイルなど)と非リソース(ディレクトリなど)を返します。イテラブルは、サブディレクトリへの再帰は行いません。

  package は、名前または `Package` の要件に適合するモジュールオブジェクトのいずれかです。

## `importlib.machinery` -- インポータおよびパスフック

ソースコード: Lib/importlib/machinery.py

このモジュールには、 `import` がモジュールを検索してロードするのに役立つ様々なオブジェクトがあります。

`importlib.machinery.``SOURCE_SUFFIXES`

  認識されているソースモジュールのファイル接尾辞を表す文字列のリストです。

  バージョン 3.3 で追加.

`importlib.machinery.``DEBUG_BYTECODE_SUFFIXES`

  最適化されていないバイトコードモジュールのファイル接尾辞を表す文字列のリストです。

  バージョン 3.3 で追加.

  バージョン 3.5 で非推奨: 代わりに `BYTECODE_SUFFIXES` を使ってください。

`importlib.machinery.``OPTIMIZED_BYTECODE_SUFFIXES`

  最適化されたバイトコードモジュールのファイル接尾辞を表す文字列のリストです。

  バージョン 3.3 で追加.

  バージョン 3.5 で非推奨: 代わりに `BYTECODE_SUFFIXES` を使ってください。

`importlib.machinery.``BYTECODE_SUFFIXES`

  認識されているバイトコードモジュールのファイル接尾辞を表す文字列のリストです (先頭のドットを含みます)。

  バージョン 3.3 で追加.

  バージョン 3.5 で変更: この値は `__debug__` に依存しなくなりました。

`importlib.machinery.``EXTENSION_SUFFIXES`

  認識されている最適化された拡張モジュールのファイル接尾辞を表す文字列のリストです。

  バージョン 3.3 で追加.

`importlib.machinery.``all_suffixes`()

  標準のインポート機構によって認識されているすべてのファイル接尾辞を表す文字列の組み合わせられたリストを返します。これが役立つのは、あるファイルシステムパスがモジュールを参照する可能性があるかだけを知りたくて、そのモジュールの種類を詳しく知る必要はないコード (例えば `inspect.getmodulename()`) です。

  バージョン 3.3 で追加.

class `importlib.machinery.``BuiltinImporter`

  組み込みモジュールの importer です。すべての既知のモジュールは `sys.builtin_module_names` に列挙されています。このクラスは `importlib.abc.MetaPathFinder` および `importlib.abc.InspectLoader` 抽象基底クラスを実装します。

  インスタンス化の必要性を軽減するため、このクラスにはクラスメソッドだけが定義されています。

  バージョン 3.5 で変更: PEP 489 の一環として、ビルトインインポーターは `Loader.create_module()` と `Loader.exec_module()` を実装しています。

class `importlib.machinery.``FrozenImporter`

  フリーズされたモジュールの インポーター です。このクラスは `importlib.abc.MetaPathFinder` および `importlib.abc.InspectLoader` 抽象基底クラスを実装します。

  インスタンス化の必要性を軽減するため、このクラスにはクラスメソッドだけが定義されています。

  バージョン 3.4 で変更: Gained `create_module()` and `exec_module()` methods.

class `importlib.machinery.``WindowsRegistryFinder`

  Windows レジストリで宣言されたモジュールの finder です。このクラスは `importlib.abc.MetaPathFinder` 抽象基底クラスを実装します。

  インスタンス化の必要性を軽減するため、このクラスにはクラスメソッドだけが定義されています。

  バージョン 3.3 で追加.

  バージョン 3.6 で非推奨: 代わりに `site` の設定を使ってください。 Python の将来のバージョンでは、デフォルトでこのファインダーが使えなくなるかもしれません。

class `importlib.machinery.``PathFinder`

  `sys.path` およびパッケージの `__path__` 属性の Finder です。このクラスは `importlib.abc.MetaPathFinder` 抽象基底クラスを実装します。

  インスタンス化の必要性を軽減するため、このクラスにはクラスメソッドだけが定義されています。

  classmethod `find_spec`(fullname, path=None, target=None)

    `sys.path` または定義されていれば path から、 fullname で指定されたモジュールの スペック の検索を試みるクラスメソッドです。検索されるそれぞれのパスエントリに対して `sys.path_importer_cache` が検査されます。偽でないオブジェクトが見つかれば、それが目的のモジュールを検索するための パスエントリ・ファインダー として使われます。 `sys.path_importer_cache` に目的のエントリが見つからなければ、パスエントリに対するファインダーが `sys.path_hooks` から検索され、見つかれば、それが `sys.path_importer_cache` に保管されるとともに、モジュールについて問い合わせられます。それでもファインダーが見つからなければ `None` が保管され、また返されます。

    バージョン 3.4 で追加.

    バージョン 3.5 で変更: もしカレントワーキングディレクトリ -- 空の文字列によって表されている -- がすでに有効でなければ、 `None` が返されますが値は `sys.path_importer_cache` にキャッシュされません。

  classmethod `find_module`(fullname, path=None)

    `find_spec()` まわりのレガシーなラッパです。

    バージョン 3.4 で非推奨: 代わりに `find_spec()` を使用してください。

  classmethod `invalidate_caches`()

    Calls `importlib.abc.PathEntryFinder.invalidate_caches()` on all finders stored in `sys.path_importer_cache` that define the method. Otherwise entries in `sys.path_importer_cache` set to `None` are deleted.

    バージョン 3.7 で変更: Entries of `None` in `sys.path_importer_cache` are deleted.

  バージョン 3.4 で変更: `''` (すなわち空の文字列) に対してはカレントワーキングディレクトリとともに `sys.path_hooks` のオブジェクトを呼び出します。

class `importlib.machinery.``FileFinder`(path, *loader_details)

  ファイルシステムからの結果をキャッシュする `importlib.abc.PathEntryFinder` の具象実装です。

  path 引数は検索を担当するファインダーのディレクトリです。

  loader_details 引数は、可変個の 2 要素タプルで、それぞれがローダーとローダーが認識するファイル接尾辞のシーケンスとを含みます。ローダーは、呼び出し可能でモジュール名と見つかったファイルのパスとの 2 引数を受け付けることを期待されます。

  ファインダーはモジュール検索のたびに stat を呼び出し、必要に応じてディレクトリの内容をキャッシュすることで、コードキャッシュが古くなっていないことを確かめます。キャッシュの古さはオペレーティングシステムのファイルシステムのステート情報の粒度に依存しますから、モジュールを検索し、新しいファイルを作成し、その後に新しいファイルが表すモジュールを検索する、という競合状態の可能性があります。この操作が stat の呼び出しの粒度に収まるほど速く起こると、モジュールの検索が失敗します。これを防ぐためには、モジュールを動的に作成する際に、必ず `importlib.invalidate_caches()` を呼び出してください。

  バージョン 3.3 で追加.

  `path`

    ファインダーが検索されるパスです。

  `find_spec`(fullname, target=None)

    `path` 内で fullname を扱うスペックの探索を試みます。

    バージョン 3.4 で追加.

  `find_loader`(fullname)

    `path` 内で fullname を扱うローダーの検索を試みます。

    バージョン 3.10 で非推奨: 代わりに `find_spec()` を使用してください。

  `invalidate_caches`()

    内部キャッシュを完全に消去します。

  classmethod `path_hook`(*loader_details)

    `sys.path_hooks` で使用するクロージャを返すクラスメソッドです。クロージャに直接渡された path 引数を直接的に、 loader_details を間接的に使って、 `FileFinder` のインスタンスが返されます。

    クロージャへの引数が存在するディレクトリでなければ、 `ImportError` が送出されます。

class `importlib.machinery.``SourceFileLoader`(fullname, path)

  `importlib.abc.FileLoader` を継承し、その他いくつかのメソッドの具象実装を提供する、 `importlib.abc.SourceLoader` の具象実装です。

  バージョン 3.3 で追加.

  `name`

    このローダーが扱うモジュールの名前です。

  `path`

    ソースファイルへのパスです。

  `is_package`(fullname)

    `path` がパッケージを表すとき `True` を返します。

  `path_stats`(path)

    `importlib.abc.SourceLoader.path_stats()` の具象実装です。

  `set_data`(path, data)

    `importlib.abc.SourceLoader.set_data()` の具象実装です。

  `load_module`(name=None)

    ロードするモジュールの名前指定がオプションの、 `importlib.abc.Loader.load_module()` の具象実装です。

    バージョン 3.6 で非推奨: 代わりに `importlib.abc.Loader.exec_module()` を使用してください。

class `importlib.machinery.``SourcelessFileLoader`(fullname, path)

  バイトコードファイル (すなわちソースコードファイルが存在しない) をインポートできる `importlib.abc.FileLoader` の具象実装です。

  注意として、バイトコードを直接使う (つまりソースコードファイルがない) と、そのモジュールはすべての Python 実装では使用できないし、新しいバージョンの Python ではバイトコードフォーマットが変更されていたら使用できません。

  バージョン 3.3 で追加.

  `name`

    ローダーが扱うモジュールの名前です。

  `path`

    バイトコードファイルへのパスです。

  `is_package`(fullname)

    そのモジュールがパッケージであるかを `path` に基づいて決定します。

  `get_code`(fullname)

    `path` から作成された `name` のコードオブジェクトを返します。

  `get_source`(fullname)

    このローダーが使われたとき、バイトコードファイルのソースがなければ `None` を返します。

  `load_module`(name=None)

  ロードするモジュールの名前指定がオプションの、 `importlib.abc.Loader.load_module()` の具象実装です。

  バージョン 3.6 で非推奨: 代わりに `importlib.abc.Loader.exec_module()` を使用してください。

class `importlib.machinery.``ExtensionFileLoader`(fullname, path)

  拡張モジュールのための `importlib.abc.ExecutionLoader` の具象実装です。

  fullname 引数はローダーがサポートするモジュールの名前を指定します。path 引数は拡張モジュールのファイルへのパスです。

  バージョン 3.3 で追加.

  `name`

    ローダーがサポートするモジュールの名前です。

  `path`

    拡張モジュールへのパスです。

  `create_module`(spec)

    与えられたスペックから PEP 489 に従ってモジュールオブジェクトを作成します。

    バージョン 3.5 で追加.

  `exec_module`(module)

    与えられたモジュールオブジェクトを PEP 489 に従って初期化します。

    バージョン 3.5 で追加.

  `is_package`(fullname)

    `EXTENSION_SUFFIXES` に基づいて、ファイルパスがパッケージの `__init__` モジュールを指していれば `True` を返します。

  `get_code`(fullname)

    拡張モジュールにコードオブジェクトがなければ `None` を返します。

  `get_source`(fullname)

    拡張モジュールにソースコードがなければ `None` を返します。

  `get_filename`(fullname)

    `path` を返します。

    バージョン 3.4 で追加.

class `importlib.machinery.``ModuleSpec`(name, loader, *, origin=None, loader_state=None, is_package=None)

  モジュールのインポートシステムに関する状態の仕様。 これは通常はモジュールの `__spec__` 属性として公開されています。 この後の解説では、モジュールオブジェクトから直接利用できる属性で、それぞれの仕様に対応しているものの名前が括弧書きで書かれています。 例えば、 `module.__spec__.origin == module.__file__` です。 ただし、属性の 値 はたいていは同一ですが、2つのオブジェクトどうしは同期されないため、異なっている可能性があることに注意してください。 例えば、モジュールの `__path__` を実行時に更新できますが、 `__spec__.submodule_search_locations` に自動的には反映されません。

  バージョン 3.4 で追加.

  `name`

  (`__name__`)

  A string for the fully qualified name of the module.

  `loader`

  (`__loader__`)

  The Loader that should be used when loading the module. Finders should always set this.

  `origin`

  (`__file__`)

  Name of the place from which the module is loaded, e.g. "builtin" for built-in modules and the filename for modules loaded from source. Normally "origin" should be set, but it may be `None` (the default) which indicates it is unspecified (e.g. for namespace packages).

  `submodule_search_locations`

  (`__path__`)

  パッケージの場合サブモジュールを見付けるべき場所を表す文字列のリスト (そうでない場合は `None`) です。

  `loader_state`

  ロード中に使う拡張モジュール指定のデータのコンテナ (または `None`) です。

  `cached`

  (`__cached__`)

  コンパイルされたモジュールを保存すべき場所を表す文字列 (または `None`) です。

  `parent`

  (`__package__`)

  (Read-only) The fully qualified name of the package under which the module should be loaded as a submodule (or the empty string for top-level modules). For packages, it is the same as `__name__`.

  `has_location`

  モジュールの "origin" 属性がロード可能な場所を参照しているかどうかを示すブール値です。

## `importlib.util` -- インポータのためのユーティリティコード

ソースコード: Lib/importlib/util.py

このモジュールには、 インポーター の構築を助ける様々なオブジェクトがあります。

`importlib.util.``MAGIC_NUMBER`

  バイトコードバージョン番号を表しているバイト列。バイトコードのロード／書き込みについてヘルプが必要なら `importlib.abc.SourceLoader` を参照してください。

  バージョン 3.4 で追加.

`importlib.util.``cache_from_source`(path, debug_override=None, *, optimization=None)

  ソース path に関連付けられたバイトコンパイルされたファイルの PEP 3147/PEP 488 パスを返します。例えば、 path が `/foo/bar/baz.py` なら、 Python 3.2 の場合返り値は `/foo/bar/__pycache__/baz.cpython-32.pyc` になります。 `cpython-32` という文字列は、現在のマジックタグから得られます (マジックタグについては `get_tag()` を参照; `sys.implementation.cache_tag` が未定義なら `NotImplementedError` が送出されます。)

  optimization パラメータは、バイトコードファイルの最適化レベルを指定するために使われます。空文字列は最適化しないことを表します。したがって、 optimization が `''` のとき `/foo/bar/baz.py` に対して `/foo/bar/__pycache__/baz.cpython-32.pyc` というバイトコードパスが返ります。 `None` にするとインタープリタの最適化レベルが使われます。それ以外では値の文字列表現が使われます。したがって、 optimization が `2` のとき `/foo/bar/baz.py` に対して `/foo/bar/__pycache__/baz.cpython-32.opt-2.pyc` というバイトコードパスが返ります。 optimization の文字列表現は英数字だけが可能で、そうでなければ `ValueError` が上げられます。

  debug_override パラメータは deprecated で、システムの `__debug__` 値をオーバーライドするために使用できます。 `True` 値は optimization を空文字列に設定するのと等価です。 `False` 値は optimization を `1` に設定するのと同等です。もし debug_override と optimization のどちらも `None` 以外であれば `TypeError` が上げられます。

  バージョン 3.4 で追加.

  バージョン 3.5 で変更: optimization パラメータが追加され、 debug_override パラメータは deprecated になりました。

  バージョン 3.6 で変更: path-like object を受け入れるようになりました。

`importlib.util.``source_from_cache`(path)

  PEP 3147 ファイル名への path が与えられると、関連するソースコードのファイルパスを返します。例えば、 path が `/foo/bar/__pycache__/baz.cpython-32.pyc` なら、返されるパスは `/foo/bar/baz.py` になります。 path は存在する必要はありませんが、 PEP 3147 または PEP 488 フォーマットに一致しない場合は `ValueError` が送出されます。 `sys.implementation.cache_tag` が定義されていない場合、 `NotImplementedError` が送出されます。

  バージョン 3.4 で追加.

  バージョン 3.6 で変更: path-like object を受け入れるようになりました。

`importlib.util.``decode_source`(source_bytes)

  与えられたソースコードを表すバイト列をデコードして、文字列としてそれを一般的な改行形式 (universal newlines) で返します (`importlib.abc.InspectLoader.get_source()` で要求されるように)。

  バージョン 3.4 で追加.

`importlib.util.``resolve_name`(name, package)

  相対的なモジュール名を解決して絶対的なものにします。

  name の先頭にドットがなければ、単に name が返されます。これにより、例えば `importlib.util.resolve_name('sys', __spec__.parent)` を使うときに package 変数が必要かどうかを確認する必要がなくなります。

  `ImportError` is raised if name is a relative module name but package is a false value (e.g. `None` or the empty string). `ImportError` is also raised a relative name would escape its containing package (e.g. requesting `..bacon` from within the `spam` package).

  バージョン 3.3 で追加.

  バージョン 3.9 で変更: To improve consistency with import statements, raise `ImportError` instead of `ValueError` for invalid relative import attempts.

`importlib.util.``find_spec`(name, package=None)

  モジュールの spec を、オプションで指定された package 名に対する相対で検索します。モジュールが `sys.modules` にあれば、 `sys.modules[name].__spec__` が返されます (ただしスペックが `None` であるか設定されていなければ `ValueError` が送出されます)。なければ、 `sys.meta_path` を使った検索がなされます。スペックが見つからなければ `None` が返ります。

  name がサブモジュールを示している (ドットを含む) 場合、親モジュールは自動的にインポートされます。

  name と package は `import_module()` に対するものと同じように機能します。

  バージョン 3.4 で追加.

  バージョン 3.7 で変更: Raises `ModuleNotFoundError` instead of `AttributeError` if package is in fact not a package (i.e. lacks a `__path__` attribute).

`importlib.util.``module_from_spec`(spec)

  spec と `spec.loader.create_module` に基づいて新しいモジュールを作ります。

  `spec.loader.create_module` が `None` を返さない場合は、既に存在するどの属性もリセットされません。また、 spec にアクセスしたり属性をモジュールに設定したりする際に `AttributeError` 例外が起きても例外は送出されません。

  この関数は、新しいモジュールを作る方法として `types.ModuleType` よりも推奨されます。なぜなら、できるだけ多くのインポートコントロールされた属性をモジュールに設定するために spec が使用されるからです。

  バージョン 3.5 で追加.

`@``importlib.util.``module_for_loader`

  ロードに使う適切なモジュールオブジェクトの選択を扱うための、 `importlib.abc.Loader.load_module()` への decorator です。このデコレータメソッドのシグニチャは、2 つの位置引数をとることを期待されます (例えば `load_module(self, module)`) 。第2引数はローダーによって使われるモジュール object になります。なお、このデコレータは 2 つの引数を想定するため、スタティックメソッドには働きません。

  デコレートされたメソッドは、 loader がロードしようとするモジュールの name を受け取ります。そのモジュールが `sys.modules` に見つからなければ新しいモジュールが構築されます。モジュールの出所に関わらず、 `__loader__` は self に設定され、 (もし利用可能なら) `__package__` は `importlib.abc.InspectLoader.is_package()` の戻り値に基づいて設定されます。これらの属性は、リロードをサポートするために無条件に設定されます。

  デコレートされたメソッドによって例外が送出されたとき、モジュールが `sys.modules` に加えられていたら、部分的に初期化されたモジュールが `sys.modules` に残らないよう、そのモジュールは取り除かれます。モジュールが既に `sys.modules` にあったなら、それは残されます。

  バージョン 3.3 で変更: `__loader__` および `__package__` は (可能なら) 自動的に設定されます。

  バージョン 3.4 で変更: リロードをサポートするために `__name__` `__loader__` `__package__` は無条件に設定されます。

  バージョン 3.4 で非推奨: インポート機構はこの関数が提供する全機能を直接実行するようになりました。

`@``importlib.util.``set_loader`

  返されたモジュールの `__loader__` 属性を設定する、 `importlib.abc.Loader.load_module()` への decorator です。属性が既に設定されていたら、このデコレータは何もしません。ラップされたメソッド (すなわち `self`) への1つ目の位置引数は `__loader__` に設定される値であると仮定されます。

  バージョン 3.4 で変更: もし `__loader__` 属性が `None` に設定されていれば、属性が存在しないかのように `__loader__` を設定します。

  バージョン 3.4 で非推奨: インポート機構はこれを自動的に考慮するようになりました。

`@``importlib.util.``set_package`

  `__package__` 属性を戻り値のモジュールに設定するための、 `importlib.abc.Loader.load_module()` への decorator です。もし `__package__` が設定されていて `None` 以外の値を持っているなら、それは変更されません。

  バージョン 3.4 で非推奨: インポート機構はこれを自動的に考慮するようになりました。

`importlib.util.``spec_from_loader`(name, loader, *, origin=None, is_package=None)

  この関数は、スペックに不足している情報を埋めるために `ModuleSpec` のような利用可能な loader API を使います。

  バージョン 3.4 で追加.

`importlib.util.``spec_from_file_location`(name, location, *, loader=None, submodule_search_locations=None)

  ファイルへのパスにもとづいて `ModuleSpec` インスタンスを生成するためのファクトリー関数。不足している情報は、ローダー API を利用してスペックから得られる情報と、モジュールがファイルベースであるという暗黙的な情報によって埋められます。

  バージョン 3.4 で追加.

  バージョン 3.6 で変更: path-like object を受け入れるようになりました。

`importlib.util.``source_hash`(source_bytes)

  Return the hash of source_bytes as bytes. A hash-based `.pyc` file embeds the `source_hash()` of the corresponding source file's contents in its header.

  バージョン 3.7 で追加.

class `importlib.util.``LazyLoader`(loader)

  モジュールが属性アクセスできるようになるまで、モジュールのローダーの実行を遅延するクラス。

  This class only works with loaders that define `exec_module()` as control over what module type is used for the module is required. For those same reasons, the loader's `create_module()` method must return `None` or a type for which its `__class__` attribute can be mutated along with not using slots. Finally, modules which substitute the object placed into `sys.modules` will not work as there is no way to properly replace the module references throughout the interpreter safely; `ValueError` is raised if such a substitution is detected.

  注釈

  起動時間が重要なプロジェクトでは、もし決して使われないモジュールがあれば、このクラスを使ってモジュールをロードするコストを最小化できるかもしれません。スタートアップ時間が重要でないプロジェクトでは、遅延されたロードの際に発生して文脈の外で起こるエラーメッセージのため、このクラスの使用は 著しく 推奨されません。

  バージョン 3.5 で追加.

  バージョン 3.6 で変更: Began calling `create_module()`, removing the compatibility warning for `importlib.machinery.BuiltinImporter` and `importlib.machinery.ExtensionFileLoader`.

  classmethod `factory`(loader)

    A class method which returns a callable that creates a lazy loader. This is meant to be used in situations where the loader is passed by class instead of by instance.

        suffixes = importlib.machinery.SOURCE_SUFFIXES
        loader = importlib.machinery.SourceFileLoader
        lazy_loader = importlib.util.LazyLoader.factory(loader)
        finder = importlib.machinery.FileFinder(path, (lazy_loader, suffixes))

## 使用例

### プログラムからのインポート

プログラムからモジュールをインポートするには、 `importlib.import_module()` を使ってください。

    import importlib

    itertools = importlib.import_module('itertools')

### モジュールがインポートできるか確認する

インポートを実際に行わずに、あるモジュールがインポートできるかを知る必要がある場合は、 `importlib.util.find_spec()` を使ってください。

Note that if `name` is a submodule (contains a dot), `importlib.util.find_spec()` will import the parent module.

    import importlib.util
    import sys

    # For illustrative purposes.
    name = 'itertools'

    if name in sys.modules:
        print(f"{name!r} already in sys.modules")
    elif (spec := importlib.util.find_spec(name)) is not None:
        # If you chose to perform the actual import ...
        module = importlib.util.module_from_spec(spec)
        sys.modules[name] = module
        spec.loader.exec_module(module)
        print(f"{name!r} has been imported")
    else:
        print(f"can't find the {name!r} module")

### ソースファイルから直接インポートする

To import a Python source file directly, use the following recipe (Python 3.5 and newer only):

    import importlib.util
    import sys

    # For illustrative purposes.
    import tokenize
    file_path = tokenize.__file__
    module_name = tokenize.__name__

    spec = importlib.util.spec_from_file_location(module_name, file_path)
    module = importlib.util.module_from_spec(spec)
    sys.modules[module_name] = module
    spec.loader.exec_module(module)

### Implementing lazy imports

The example below shows how to implement lazy imports:

    >>> import importlib.util
    >>> import sys
    >>> def lazy_import(name):
    ...     spec = importlib.util.find_spec(name)
    ...     loader = importlib.util.LazyLoader(spec.loader)
    ...     spec.loader = loader
    ...     module = importlib.util.module_from_spec(spec)
    ...     sys.modules[name] = module
    ...     loader.exec_module(module)
    ...     return module
    ...
    >>> lazy_typing = lazy_import("typing")
    >>> #lazy_typing is a real module object,
    >>> #but it is not loaded in memory yet.
    >>> lazy_typing.TYPE_CHECKING
    False

### インポーターのセットアップ

For deep customizations of import, you typically want to implement an importer. This means managing both the finder and loader side of things. For finders there are two flavours to choose from depending on your needs: a meta path finder or a path entry finder. The former is what you would put on `sys.meta_path` while the latter is what you create using a path entry hook on `sys.path_hooks` which works with `sys.path` entries to potentially create a finder. This example will show you how to register your own importers so that import will use them (for creating an importer for yourself, read the documentation for the appropriate classes defined within this package):

    import importlib.machinery
    import sys

    # For illustrative purposes only.
    SpamMetaPathFinder = importlib.machinery.PathFinder
    SpamPathEntryFinder = importlib.machinery.FileFinder
    loader_details = (importlib.machinery.SourceFileLoader,
                      importlib.machinery.SOURCE_SUFFIXES)

    # Setting up a meta path finder.
    # Make sure to put the finder in the proper location in the list in terms of
    # priority.
    sys.meta_path.append(SpamMetaPathFinder)

    # Setting up a path entry finder.
    # Make sure to put the path hook in the proper location in the list in terms
    # of priority.
    sys.path_hooks.append(SpamPathEntryFinder.path_hook(loader_details))

### Approximating `importlib.import_module()`

Import itself is implemented in Python code, making it possible to expose most of the import machinery through importlib. The following helps illustrate the various APIs that importlib exposes by providing an approximate implementation of `importlib.import_module()` (Python 3.4 and newer for the importlib usage, Python 3.6 and newer for other parts of the code).

    import importlib.util
    import sys

    def import_module(name, package=None):
        """An approximate implementation of import."""
        absolute_name = importlib.util.resolve_name(name, package)
        try:
            return sys.modules[absolute_name]
        except KeyError:
            pass

        path = None
        if '.' in absolute_name:
            parent_name, _, child_name = absolute_name.rpartition('.')
            parent_module = import_module(parent_name)
            path = parent_module.__spec__.submodule_search_locations
        for finder in sys.meta_path:
            spec = finder.find_spec(absolute_name, path)
            if spec is not None:
                break
        else:
            msg = f'No module named {absolute_name!r}'
            raise ModuleNotFoundError(msg, name=absolute_name)
        module = importlib.util.module_from_spec(spec)
        sys.modules[absolute_name] = module
        spec.loader.exec_module(module)
        if path is not None:
            setattr(parent_module, child_name, module)
        return module