# 3.21 `imp` -- `import`内部へアクセスする

このモジュールは`import`文を実装するために使われているメカニズムへのインターフェイスを提供します。次の定数と関数が定義されています:

`get_magic`( | )

  バイトコンパイルされたコードファイル(.pycファイル)を認識するために使われるマジック文字列値を返します。(この値はPythonの各バージョンで異なります。)

`get_suffixes`( | )

  三つ組みのリストを返します。それぞれはモジュールの特定の型を説明しています。各三つ組みは形式`(suffix, mode, type)`を持ちます。ここで、suffixは探すファイル名を作るためにモジュール名に追加する文字列です。そのファイルをオープンするために、modeは組み込み`open()`関数へ渡されるモード文字列です(これはテキストファイル対しては`'r'`、バイナリファイルに対しては`'rb'`となります)。typeはファイル型で、以下で説明する値`PY_SOURCE`、`PY_COMPILED`、あるいは、`C_EXTENSION`の一つを取ります。

`find_module`( | name[, path])

  検索パスpath上でモジュールnameを見つけようとします。pathがディレクトリ名のリストならば、上の`get_suffixes()`が返す拡張子のいずれかを伴ったファイルを各ディレクトリの中で検索します。リスト内の有効でない名前は黙って無視されます(しかし、すべてのリスト項目は文字列でなければならない)。pathが省略されるか`None`ならば、`sys.path`のディレクトリ名のリストが検索されます。しかし、最初にいくつか特別な場所を検索します。所定の名前(`C_BUILTIN`)をもつ組み込みモジュールを見つけようとします。それから、フリーズされたモジュール(`PY_FROZEN`)、同様にいくつかのシステムと他の場所がみられます(Macでは、リソース(`PY_RESOURCE`)を探します。Windowsでは、特定のファイルを指すレジストリの中を見ます)。

  検索が成功すれば、戻り値は三つ組み`(file, pathname, description)`です。ここで、fileは先頭に位置を合わされたオープンファイルオブジェクトで、pathnameは見つかったファイルのパス名です。そして、descriptionは`get_suffixes()`が返すリストに含まれているような三つ組みで、見つかったモジュールの種類を説明しています。モジュールがファイルの中にあるならば、返されたfileは`None`で、filenameは空文字列、descriptionタプルはその拡張子とモードに対して空文字列を含みます。モジュール型は上の括弧の中に示されます。検索が失敗すれば、`ImportError`が発生します。他の例外は引数または環境に問題があることを示唆します。

  この関数は階層的なモジュール名(ドットを含んだ名前)を扱いません。P.M、すなわち、パッケージPのサブモジュールMを見つけるためには、パッケージPを見つけてロードするために`find_module()`と`load_module()`を使い、それから`P.__path__`に設定されたpath引数とともに`find_module()`を使ってください。P自身がドット名のときは、このレシピを再帰的に適用してください。

`load_module`( | name, file, filename, description)

  `find_module()`を使って(あるいは、互換性のある結果を作り出す検索を行って)以前見つけたモジュールをロードします。この関数はモジュールをインポートするという以上のことを行います: モジュールが既にインポートされているならば、`reload()`と同じです!。name引数は(これがパッケージのサブモジュールならばパッケージ名を含む)完全なモジュール名を示します。file引数はオープンしたファイルで、filenameは対応するファイル名です。モジュールがファイルからロードされようとしていないとき、これらはそれぞれ`None`と`''`であっても構いません。`get_suffixes()`が返すようにdescription引数はタプルで、どの種類のモジュールがロードされなければならないかを説明するものです。

  ロードが成功したならば、戻り値はモジュールオブジェクトです。そうでなければ、例外(たいていは`ImportError`)が発生します。

  重要: file引数が`None`でなければ、例外が発生した時でさえ呼び出し側にはそれを閉じる責任があります。これを行うには、`try` ... `finally`文をつかうことが最も良いです。

`new_module`( | name)

  nameという名前の新しい空モジュールオブジェクトを返します。このオブジェクトは`sys.modules`に挿入されません。

`lock_held`( | )

  現在インポートロックが維持されているならば、`True`を返します。そうでなければ、`False`を返します。スレッドのないプラットホームでは、常に`False`を返します。

  スレッドのあるプラットホームでは、インポートが完了するまでインポートを実行するスレッドは内部ロックを維持します。このロックは元のインポートが完了するまで他のスレッドがインポートすることを阻止します。言い換えると、元のスレッドがそのインポート(および、もしあるならば、それによって引き起こされるインポート)の途中で構築した不完全なモジュールオブジェクトを、他のスレッドが見られないようにします。

`acquire_lock`( | )

  実行中のスレッドでインタープリタのインポートロックを取得します。スレッドセーフ なインポートフックでは、インポート時にこのロックを取得します。 スレッドのないプラットホームではこの関数は何もしません。 バージョン2.3 以降で新規追加された 仕様です。

`release_lock`( | )

  インタープリタのインポートロックを解放します。 スレッドのないプラットホームではこの関数は何もしません。 バージョン2.3 以降で新規追加された 仕様です。

整数値をもつ次の定数はこのモジュールの中で定義されており、`find_module()`の検索結果を表すために使われます。

`PY_SOURCE`
  ソースファイルとしてモジュールが発見された。

`PY_COMPILED`
  コンパイルされたコードオブジェクトファイルとしてモジュールが発見された。

`C_EXTENSION`
  動的にロード可能な共有ライブラリとしてモジュールが発見された。

`PY_RESOURCE`
  モジュールがMacintoshリソースとして発見された。この値はMacintoshでのみ返される。

`PKG_DIRECTORY`
  パッケージディレクトリとしてモジュールが発見された。

`C_BUILTIN`
  モジュールが組み込みモジュールとして発見された。

`PY_FROZEN`
  モジュールがフリーズされたモジュールとして発見された(`init_frozen()`を参照)。

次の定数と関数は旧式のものです。それらの機能は`find_module()`や`load_module()`を使って利用できます。後方互換性のために残されています:

`SEARCH_ERROR`
  使われていません。

`init_builtin`( | name)

  nameという名前の組み込みモジュールを初期化し、そのモジュールオブジェクトを返します。モジュールが既に初期化されている場合は、再度初期化されます。いくつかのモジュールは二度初期化することができません。 -- これを再び初期化しようとすると、`ImportError`例外が発生します。nameという名前の組み込みモジュールがない場合は、`None`を返します。

`init_frozen`( | name)

  nameという名前のフリーズされたモジュールを初期化し、モジュールオブジェクトを返します。モジュールが既に初期化されている場合は、再度初期化されます。nameという名前のフリーズされたモジュールがない場合は、`None`を返します。(フリーズされたモジュールはPythonで書かれたモジュールで、そのコンパイルされたバイトコードオブジェクトがPythonのfreezeユーティリティを使ってカスタムビルトPythonインタープリタへ組み込まれています。差し当たり、Tools/freeze/を参照してください。)

`is_builtin`( | name)

  nameという名前の再度初期化できる組み込みモジュールがある場合は、`1`を返します。nameという名前の再度初期化できない組み込みモジュールがある場合は、`-1`を返します(`init_builtin()`を参照してください)。nameという名前の組み込みモジュールがない場合は、`0`を返します。

`is_frozen`( | name)

  nameという名前のフリーズされたモジュール(`init_frozen()`を参照)がある場合は、`True`を返します。または、そのようなモジュールがない場合は、`False`を返します。

`load_compiled`( | name, pathname, file)

  バイトコンパイルされたコードファイルとして実装されているモジュールをロードして初期化し、そのモジュールオブジェクトを返します。モジュールが既に初期化されている場合は、再度初期化されます。name引数はモジュールオブジェクトを作ったり、アクセスするために使います。pathname引数はバイトコンパイルされたコードファイルを指します。file引数はバイトコンパイルされたコードファイルで、バイナリモードでオープンされ、先頭からアクセスされます。現在は、ユーザ定義のファイルをエミュレートするクラスではなく、実際のファイルオブジェクトでなければなりません。

`load_dynamic`( | name, pathname[, file])

  動的ロード可能な共有ライブラリとして実装されているモジュールをロードして初期化します。モジュールが既に初期化されている場合は、再度初期化します。いくつかのモジュールではそれができずに、例外を発生するかもしれません。pathname引数は共有ライブラリを指していなければなりません。name引数は初期化関数の名前を作るために使われます。共有ライブラリの"`initname()`"という名前の外部C関数が呼び出されます。オプションのfile引数は無視されます。(注意: 共有ライブラリはシステムに大きく依存します。また、すべてのシステムがそれをサポートしているわけではありません。)

`load_source`( | name, pathname, file)

  Pythonソースファイルとして実装されているモジュールをロードして初期化し、モジュールオブジェクトを返します。モジュールが既に初期化されている場合は、再度初期化します。name引数はモジュールオブジェクトを作成したり、アクセスしたりするために使われます。pathname引数はソースファイルを指します。file引数はソースファイルで、テキストとして読み込むためにオープンされ、先頭からアクセスされます。現在は、ユーザ定義のファイルをエミュレートするクラスではなく、実際のファイルオブジェクトでなければなりません。(拡張子.pycまたは.pyoをもつ)正しく対応するバイトコンパイルされたファイルが存在する場合は、与えられたソースファイルを構文解析する代わりにそれが使われることに注意してください。