"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" を返します。

class importlib.abc.MetaPathFinder

   *meta path finder* を表す抽象基底クラスです。互換性のため、これは
   "Finder" のサブクラスです。

   バージョン 3.3 で追加.

   find_spec(fullname, path, target=None)

      An abstract method for finding a *spec* for the specified
      module.  If this is a top-level import, *path* will be "None".
      Otherwise, this is a search for a subpackage or module and
      *path* will be the value of "__path__" from the parent package.
      If a spec cannot be found, "None" is returned. When passed in,
      "target" is a module object that the finder may use to make a
      more educated guess about what spec to return.
      "importlib.util.spec_from_loader()" may be useful for
      implementing concrete "MetaPathFinders".

      バージョン 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

   *パスエントリ・ファインダー* を表す抽象基底クラスです。
   "MetaPathFinder" と似ているところがありますが、 "PathEntryFinder"
   は "PathFinder" の与えるパスに基づくインポートサブシステムの中での
   み使うことが意図されています。この抽象基底クラスは互換性の理由だけ
   のために、 "Finder" のサブクラスにしてあります。

   バージョン 3.3 で追加.

   find_spec(fullname, target=None)

      An abstract method for finding a *spec* for the specified
      module.  The finder will search for the module only within the
      *path entry* to which it is assigned.  If a spec cannot be
      found, "None" is returned.  When passed in, "target" is a module
      object that the finder may use to make a more educated guess
      about what spec to return. "importlib.util.spec_from_loader()"
      may be useful for implementing concrete "PathEntryFinders".

      バージョン 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()

      このファインダーで使われている内部キャッシュがあれば無効にするオ
      プションのメソッドです。キャッシュされたすべてのファインダーの無
      効化する際、 "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__"
           モジュールやパッケージの親パッケージです。そのモジュールが
           トップレベルなら、空文字列の値をとります。
           "importlib.util.module_for_loader()" デコレータで、
           "__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

   *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__" で終わらないこと。


"importlib.resources" -- Resources
==================================

**ソースコード:** Lib/importlib/resources.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.

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.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.

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.

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".

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".

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).

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)

   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.


"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* を扱うローダーの検索を試みます。

   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)

      Return "True" if "path" appears to be for a package.

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

   モジュールの完全修飾名を表す文字列です。

   loader

   ("__loader__")

   ロードに使うローダです。名前空間パッケージの場合 "None" に設定しな
   ければなりません。

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

   (読み出し専用) サブモジュールとしてモジュールが属するパッケージの完
   全修飾名 (または "None") です。

   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)

   Given the *path* to a **PEP 3147** file name, return the associated
   source code file path.  For example, if *path* is
   "/foo/bar/__pycache__/baz.cpython-32.pyc" the returned path would
   be "/foo/bar/baz.py".  *path* need not exist, however if it does
   not conform to **PEP 3147** or **PEP 488** format, a "ValueError"
   is raised. If "sys.implementation.cache_tag" is not defined,
   "NotImplementedError" is raised.

   バージョン 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', __package__)" を
   使うときに **package** 変数が必要かどうかを確認する必要がなくなりま
   す。

   **name** が相対的なモジュール名であるにもかかわらず package が偽値
   (例えば "None" や空文字列) ならば、 "ValueError" が送出されます。相
   対的な名前がそれを含むパッケージから抜け出る (例えば "spam" パッケ
   ージ内から "..bacon" を要求する) 場合にも "ValueError" が送出されま
   す。

   バージョン 3.3 で追加.

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)

   この関数は、スペックに不足している情報を埋めるために
   "InspectLoader.is_package()" のような利用可能な *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)

      遅延ローダを生成する callable を返すスタティックメソッド。これは
      、ローダーをインスタンスとしてではなくクラスとして渡すような状況
      において使われることを意図しています。

         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()" を使ってください。

   import importlib.util
   import sys

   # For illustrative purposes.
   name = 'itertools'

   spec = importlib.util.find_spec(name)
   if spec is None:
       print("can't find the itertools module")
   else:
       # If you chose to perform the actual import ...
       module = importlib.util.module_from_spec(spec)
       spec.loader.exec_module(module)
       # Adding the module to sys.modules is optional.
       sys.modules[name] = 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)
   spec.loader.exec_module(module)
   # Optional; only necessary if you want to be able to import the module
   # by name later.
   sys.modules[module_name] = module


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

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)
       spec.loader.exec_module(module)
       sys.modules[absolute_name] = module
       if path is not None:
           setattr(parent_module, child_name, module)
       return module
