30.6. importlib – The implementation of import

バージョン 3.1 で追加.

30.6.1. はじめに

The purpose of the importlib package is two-fold. One is to provide the implementation of the import statement (and thus, by extension, the __import__() function) in Python source code. This provides an implementation of import which is portable to any Python interpreter. This also provides an implementation which is easier to comprehend than one implemented in a programming language other than Python.

Two, the components to implement import are exposed in this package, making it easier for users to create their own custom objects (known generically as an importer) to participate in the import process.

参考

import 文

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

パッケージ仕様

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

__import__() 関数

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

PEP 235

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

PEP 263

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

PEP 302

新しい import フック

PEP 328
Imports: Multi-Line and Absolute/Relative
PEP 366
Main module explicit relative imports
PEP 451
A ModuleSpec Type for the Import System
PEP 3120
Using UTF-8 as the Default Source Encoding
PEP 3147
PYC Repository Directories

30.6.2. 関数

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

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

importlib.import_module(name, package=None)

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

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

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

importlib.find_loader(name, path=None)

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

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

importlib.invalidate_caches()

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

バージョン 3.3 で追加.

30.6.3. importlib.abc – import に関連する抽象基底クラス

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

ABC 階層:

object
 +-- Finder (deprecated)
 |    +-- MetaPathFinder
 |    +-- PathEntryFinder
 +-- Loader
      +-- ResourceLoader --------+
      +-- InspectLoader          |
           +-- ExecutionLoader --+
                                 +-- FileLoader
                                 +-- SourceLoader
                                      +-- PyLoader (deprecated)
                                      +-- PyPycLoader (deprecated)
class importlib.abc.Finder

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

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

find_module(fullname, path=None)

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

class importlib.abc.MetaPathFinder

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

バージョン 3.3 で追加.

find_module(fullname, path)

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

invalidate_caches()

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

class importlib.abc.PathEntryFinder

path entry finder を表す抽象基底クラスです。 MetaPathFinder と似ているところがありますが、 PathEntryFinder はパスに基づく import サブシステムの中でのみ使うことが意図されています。この抽象基底クラスは互換性のため、 Finder のサブクラスです。

バージョン 3.3 で追加.

find_loader(fullname)

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

find_module(fullname)

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

invalidate_caches()

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

class importlib.abc.Loader

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

load_module(fullname)

モジュールをロードするための抽象基底クラスです。モジュールがロードできなければ ImportError を送出し、ロードできればロードされたモジュールを返します。

要求されたモジュールが既に sys.modules に存在したなら、そのモジュールが使われリロードされる必要があります。存在しなければ、import からの再帰を防ぐため、ローダーはロードが始まる前に新しいモジュールを作成して sys.modules に挿入する必要があります。ローダーがモジュールを挿入した後にロードが失敗したなら、ローダーはそのモジュールを sys.modules から削除する必要があります。ローダーが実行を始める前に既に sys.modules にあったモジュールは、そのままにします。 importlib.util.module_for_loader() デコレータは、これらの詳細全てを扱います。

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

  • __name__

    モジュールの名前

  • __file__

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

  • __cached__

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

  • __path__

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

  • __package__

    モジュールやパッケージの親パッケージです。そのモジュールがトップレベルなら、空文字列の値をとります。 importlib.util.set_package() デコレータで、__package__ の詳細を扱えます。

  • __loader__

    モジュールをロードするのに使われたローダーです。 (組み込み import 機構はこれを設定しませんが、 loader が使われた場合は必ず設定する必要があります。)

module_repr(module)

抽象メソッドで、実装するときは与えられたモジュールの repr を文字列として計算して返します。

class importlib.abc.ResourceLoader

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

get_data(path)

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

class importlib.abc.InspectLoader

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

get_code(fullname)

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

get_source(fullname)

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

is_package(fullname)

モジュールがパッケージであれば True を返し、そうでなければ False を返す抽象メソッドです。 loader がモジュールを見つけられなかったなら ImportError が送出されます。

class importlib.abc.ExecutionLoader

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

get_filename(fullname)

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

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

class importlib.abc.FileLoader(fullname, path)

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

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

バージョン 3.3 で追加.

name

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

path

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

load_module(fullname)

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

get_filename(fullname)

path を返します。

get_data(path)

path のバイナリファイルを開いた状態で返します。

class importlib.abc.SourceLoader

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

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

path_stats(path)

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

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

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

未来の拡張のため、辞書内の他のキーは無視されます。

バージョン 3.3 で追加.

path_mtime(path)

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

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

set_data(path, data)

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

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

get_code(fullname)

InspectLoader.get_code() の実際の実装です。

load_module(fullname)

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

get_source(fullname)

InspectLoader.get_source() の実際の実装です。

is_package(fullname)

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

class importlib.abc.PyLoader

ExecutionLoader および ResourceLoader から継承する抽象基底クラスで、Python ソースモジュールのロードを楽にするように設計されています (バイトコードは扱いません。ソースおよびバイトコードの ABC は SourceLoader を参照してください)。この ABC を実装するサブクラスは、ソースコードを保管する方法を公開することのみを考えればよいです。Python ソースコードをロードすることについてその他の詳細はキーメソッドの実際の実装によって扱われます。

バージョン 3.2 で撤廃: このメソッドは廃止されており、 SourceLoader が推奨されます。また Python 3.4 にて取り除かれる予定です。Python 3.1 以降と互換性のあるサブクラスを作成する方法は、参照してください。

Python 3.1 との互換性が必要なら、Python 3.1 以降ではたらくサブクラスを実装するために、以下のイディオムを使ってください (ExecutionLoader.get_filename() を確実に実装しておいてください):

try:
    from importlib.abc import SourceLoader
except ImportError:
    from importlib.abc import PyLoader as SourceLoader


class CustomLoader(SourceLoader):
    def get_filename(self, fullname):
        """Return the path to the source file."""
        # Implement ...

    def source_path(self, fullname):
        """Implement source_path in terms of get_filename."""
        try:
            return self.get_filename(fullname)
        except ImportError:
            return None

    def is_package(self, fullname):
        """Implement is_package by looking for an __init__ file
        name as returned by get_filename."""
        filename = os.path.basename(self.get_filename(fullname))
        return os.path.splitext(filename)[0] == '__init__'
source_path(fullname)

モジュールのソースコードへのパスを返す抽象メソッドです。ソースコードがなければ None を返す必要があります。ローダーがそのモジュールを扱えないことが分かったなら ImportError を送出します。

get_filename(fullname)

source_path() に依存する importlib.abc.ExecutionLoader.get_filename() の実際の実装です。 source_path()None を返すなら、 ImportError が送出されます。

load_module(fullname)

Python ソースコードをロードする importlib.abc.Loader.load_module() の実際の実装です。この抽象メソッドから来る全ての必要な情報は、この ABC により要求されます。このメソッドによってなされる適切な仮定は、パッケージの読み込み時に __path__[os.path.dirname(__file__)] に設定されていることだけです。

get_code(fullname)

importlib.abc.InspectLoader.get_code() の完全な実装で、Python ソースコードを (source_path()get_data() を使って) 要求し、組み込みの compile() 関数でコンパイルするすることで、ソースコードからコードオブジェクトを作成します。

get_source(fullname)

importlib.abc.InspectLoader.get_source() の完全な実装です。ソースコードの取得に importlib.abc.ResourceLoader.get_data()source_path() を使います。ソースのエンコーディングを推測するのに tokenize.detect_encoding() を使います。

class importlib.abc.PyPycLoader

PyLoader を継承する抽象基底クラスです。この ABC は Python ソースとバイトコードの両方をサポートするローダーを作成するのに役立つことを意図しています。

バージョン 3.2 で撤廃: このクラスは PEP 3147 を適切にサポートするために廃止され、 SourceLoader が推奨されます。Python 3.1 との互換性が必要なら、 SourceLoaderPyLoader の両方を実装してください。その方法についての説明は PyLoader のドキュメントに書かれています。但し、この解決策はソースのない、バイトコードのみのロードをサポートしません。ソースとバイトコードファイル の組み合わせ のみサポートします。

バージョン 3.3 で変更: 読み込み時にバイトコード中の新しいソースサイズを解析する (が使わない) ように、また書き込み時にフィールドプロパティを書き出すように、更新されました。

source_mtime(fullname)

抽象メソッドで、指定されたモジュールのソースコードの更新時刻を返します。更新時刻は整数にする必要があります。ソースコードがなければ、 None を返します。モジュールが見つからなければ、 ImportError が送出されます。

bytecode_path(fullname)

抽象メソッドで、指定されたモジュールのバイトコードが存在すれば、そのパスを返します。バイトコードが (まだ) なければ、 None を返します。ローダーがそのモジュールを扱えないことが分かったなら ImportError を送出します。

get_filename(fullname)

PyLoader.source_path() および bytecode_path() に依存する ExecutionLoader.get_filename() の具象実装です。 source_path() がパスを返したなら、そのパスが返されます。そうでなくて、もし bytecode_path() がパスを返したなら、そのパスが返されます。どちらのメソッドからもパスを得られなければ、 ImportError が送出されます。

write_bytecode(fullname, bytecode)

将来使うためにローダーに bytecode を書き込ませる抽象メソッドです。バイトコードが書き込まれたなら、 True を返します。バイトコードが書き込まれなかったら、 False を返します。このメソッドは、 sys.dont_write_bytecode が真であるなら呼び出されてはなりません。 bytecode 引数はバイト文字列またはバイト配列である必要があります。

30.6.4. importlib.machinery – インポータおよびパスフック

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

importlib.machinery.SOURCE_SUFFIXES

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

バージョン 3.3 で追加.

importlib.machinery.DEBUG_BYTECODE_SUFFIXES

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

バージョン 3.3 で追加.

importlib.machinery.OPTIMIZED_BYTECODE_SUFFIXES

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

バージョン 3.3 で追加.

importlib.machinery.BYTECODE_SUFFIXES

認識されているバイトコードモジュールのファイル接尾辞を表す文字列のリストです。 __debug__ の真偽に応じて、 DEBUG_BYTECODE_SUFFIXESOPTIMIZED_BYTECODE_SUFFIXES のいずれかに設定されます。

バージョン 3.3 で追加.

importlib.machinery.EXTENSION_SUFFIXES

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

バージョン 3.3 で追加.

importlib.machinery.all_suffixes()

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

バージョン 3.3 で追加.

class importlib.machinery.BuiltinImporter

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

インスタンス化を容易にするため、クラスメソッドだけがこのクラスによって定義されます。

class importlib.machinery.FrozenImporter

フリーズされたモジュールの importer このクラスは importlib.abc.MetaPathFinder および importlib.abc.InspectLoader ABC を実装します。

インスタンス化を容易にするため、クラスメソッドだけがこのクラスによって定義されます。

class importlib.machinery.WindowsRegistryFinder

Windows レジストリで宣言されたモジュールの Finder です。このクラスは importlib.abc.Finder を実装します。

インスタンス化を容易にするため、クラスメソッドだけがこのクラスによって定義されます。

バージョン 3.3 で追加.

class importlib.machinery.PathFinder

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

インスタンス化を容易にするため、クラスメソッドだけがこのクラスによって定義されます。

classmethod find_module(fullname, path=None)

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

classmethod invalidate_caches()

sys.path_importer_cache に保管されている全てのファインダに対して importlib.abc.PathEntryFinder.invalidate_caches() を呼び出します。

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

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

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

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

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

バージョン 3.3 で追加.

path

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

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)

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

path_stats(path)

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

set_data(path, data)

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

class importlib.machinery.SourcelessFileLoader(fullname, path)

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

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

バージョン 3.3 で追加.

name

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

path

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

is_package(fullname)

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

get_code(fullname)

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

get_source(fullname)

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

class importlib.machinery.ExtensionFileLoader(fullname, path)

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

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

バージョン 3.3 で追加.

name

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

path

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

load_module(fullname)

fullnamename と同じか None であるときに限り拡張モジュールをロードします。

is_package(fullname)

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

get_code(fullname)

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

get_source(fullname)

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

30.6.5. importlib.util – インポータのためのユーティリティコード

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

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

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

デコレートされたメソッドは、 loader がロードしようとするモジュールの name を受け取ります。そのモジュールが sys.modules に見つからなければ、 nameImportError が送出されるのではなく、新しいモジュールが構築されます。新しいモジュールの __name__ 属性は name に設定され、 __loader__self に設定され、もし selfimportlib.abc.InspectLoader.is_package() が設定されているなら、 __package__ も設定されます。新しいモジュールが必要なければ、 sys.modules に見つかったモジュールがメソッドに渡されます。

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

このデコレータを使うことで、ローダーが初期化するべきモジュールオブジェクトの PEP 302 で規定された詳細の全てを、可能な限り扱えます。

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

@importlib.util.set_loader

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

注釈

このデコレータの代わりに、この機能を包摂する module_for_loader() を使うことが推奨されます。

@importlib.util.set_package

ローダーによって返されたモジュールの __package__ 属性を設定する、 loader への decorator です。 __package__ が設定されていて None 以外の値であれば、変更されません。なお、ローダーによって返されるモジュールは属性が設定されたものであり、 sys.modules に見つかったモジュールではありません。

import の前に __package__ を設定できるなら、このデコレータに頼るべきではありません。前もって設定しておくことで、モジュールのコードは属性が設定された状態で実行され、したがって初期化中にトップレベルコードから使うことができます。

注釈

このデコレータの代わりに、この機能を包摂する module_for_loader() を使うことが推奨されます。