モジュールのインポート
**********************

PyObject *PyImport_ImportModule(const char *name)
    *Return value: New reference.** Part of the Stable ABI.*

   この関数は下で述べる "PyImport_ImportModuleEx()" を単純化したインタ
   ーフェースで、 *globals* および *locals*  引数を "NULL" のままにし
   、 *level* を 0 にしたものです。 *name* 引数にドットが含まれる場合
   (あるパッケージのサブモジュールを指定している場合)、 *fromlist* 引
   数がリスト "['*']" に追加され、戻り値がモジュールを含むトップレベル
   パッケージではなく名前つきモジュール (named module) になるようにし
   ます。 (残念ながらこのやり方には、 *name* が実際にはサブモジュール
   でなくサブパッケージを指定している場合、パッケージの  "__all__"
   変数に指定されているサブモジュールがロードされてしまうという副作用
   があります。) インポートされたモジュールへの新たな参照を返します。
   失敗した場合には例外をセットし、 "NULL" を返します。インポートに失
   敗したモジュールは "sys.modules" に残りません。

   この関数は常に絶対インポートを使用します。

PyObject *PyImport_ImportModuleNoBlock(const char *name)
    *Return value: New reference.** Part of the Stable ABI.*

   この関数は、 "PyImport_ImportModule()" の廃止予定のエイリアスです。

   バージョン 3.3 で変更: この関数は、従来は別のスレッドによってインポ
   ートロックが行われていた場合は即座に失敗していました。しかし Python
   3.3 では、大部分の目的でロックスキームがモジュールごとのロックに移
   行したので、この関数の特別な振る舞いはもはや必要ではありません。

PyObject *PyImport_ImportModuleEx(const char *name, PyObject *globals, PyObject *locals, PyObject *fromlist)
    *Return value: New reference.*

   モジュールをインポートします。モジュールのインポートについては組み
   込みの Python 関数 "__import__()" を読むとよくわかります。

   戻り値は、インポートされたモジュールかトップレベルパッケージへの新
   しい参照か、失敗した場合は例外を設定して "NULL" を返します。
   "__import__()" と同じように、パッケージのサブモジュールが要求された
   ときは、空でない *fromlist* を渡された時以外は、トップレベルのパッ
   ケージを返します。

   インポートが失敗した場合は、"PyImport_ImportModule()" と同様に不完
   全なモジュールのオブジェクトを削除します。

PyObject *PyImport_ImportModuleLevelObject(PyObject *name, PyObject *globals, PyObject *locals, PyObject *fromlist, int level)
    *Return value: New reference.** Part of the Stable ABI since
   version 3.7.*

   モジュールをインポートします。モジュールのインポートについては組み
   込みの Python 関数 "__import__()" を読むとよく分かります。というの
   も、標準の "__import__()"  はこの関数を直接呼び出しているからです。

   戻り値は、インポートされたモジュールかトップレベルパッケージへの新
   しい参照か、失敗した場合は例外を設定して "NULL" を返します。
   "__import__()" と同じように、パッケージのサブモジュールが要求された
   ときは、空でない *fromlist* を渡された時以外は、トップレベルのパッ
   ケージを返します。

   バージョン 3.3 で追加.

PyObject *PyImport_ImportModuleLevel(const char *name, PyObject *globals, PyObject *locals, PyObject *fromlist, int level)
    *Return value: New reference.** Part of the Stable ABI.*

   "PyImport_ImportModuleLevelObject()" と似ていますが、name が
   Unicode オブジェクトではなく UTF-8 でエンコードされた文字列である点
   で異なります。

   バージョン 3.3 で変更: *level* にはもはや負の値は使用できません。

PyObject *PyImport_Import(PyObject *name)
    *Return value: New reference.** Part of the Stable ABI.*

   現在の "インポートフック関数" を呼び出すための高水準のインターフェ
   ースです (*level* に 0 を明示すると、絶対インポートを意味します)。
   この関数は現在のグローバル変数辞書内の "__builtins__" から
   "__import__()" 関数を呼び出します。すなわち、現在の環境にインストー
   ルされているインポートフック使ってインポートを行います。

   この関数は常に絶対インポートを使用します。

PyObject *PyImport_ReloadModule(PyObject *m)
    *Return value: New reference.** Part of the Stable ABI.*

   モジュールを再ロード (reload) します。戻り値は再ロードしたモジュー
   ルかトップレベルパッケージへの新たな参照になります。 失敗した場合に
   は例外をセットし、"NULL" を返します (その場合でも、モジュールは生成
   されている場合があります)。

PyObject *PyImport_AddModuleObject(PyObject *name)
    *Return value: Borrowed reference.** Part of the Stable ABI since
   version 3.7.*

   モジュール名に対応するモジュールオブジェクトを返します。*name* 引数
   は "package.module" の形式でもかまいません。 まずモジュール辞書に該
   当するモジュールがあるかどうか調べ、なければ新たなモジュールを生成
   してモジュール辞書に挿入します。 失敗した場合には例外をセットして
   "NULL" を返します。

   注釈:

     この関数はモジュールのインポートやロードを行いません; モジュール
     がまだロードされていなければ、空のモジュールオブジェクトを得るこ
     とになります。 "PyImport_ImportModule()" やその別形式を使ってモジ
     ュールをインポートしてください。ドット名表記で指定した *name* が
     存在しない場合、パッケージ構造は作成されません。

   バージョン 3.3 で追加.

PyObject *PyImport_AddModule(const char *name)
    *Return value: Borrowed reference.** Part of the Stable ABI.*

   "PyImport_AddModuleObject()" と似ていますが、name が UTF-8 でエンコ
   ードされた文字列ではなく Unicode オブジェクトを使用する点で異なりま
   す。

PyObject *PyImport_ExecCodeModule(const char *name, PyObject *co)
    *Return value: New reference.** Part of the Stable ABI.*

   モジュール名 ("package.module" 形式でも構いません) および Python の
   バイトコードファイルや組み込み関数 "compile()"  で得られたコードオ
   ブジェクトを元にモジュールをロードします。 モジュールオブジェクトへ
   の新たな参照を返します。 失敗した場合には例外をセットし、 "NULL" を
   返します。たとえ "PyImport_ExecCodeModule()" の処理に入った時に
   *name* が "sys.modules" に入っていたとしても、インポートに失敗した
   モジュールは "sys.modules" に残りません。 初期化の不完全なモジュー
   ルを "sys.modules" に残すのは危険であり、そのようなモジュールをイン
   ポートするコードにとっては、モジュールの状態がわからない (モジュー
   ル作者の意図から外れた壊れた状態かもしれない) からです。

   モジュールの "__spec__" と "__loader__" がまだ設定されていなければ
   、適切な値が設定されます。spec の ローダーは、モジュールの
   "__loader__" が (もし設定されていれば) それに設定され、そうでなけれ
   ば  "SourceFileLoader" のインスタンスに設定されます。

   モジュールの "__file__"  属性はコードオブジェクトの "co_filename"
   へ設定されます。もし適切な場合は、 "__cached__"  へも設定されます。

   この関数は、すでにインポートされているモジュールの場合には再ロード
   を行います。意図的にモジュールの再ロードを行う方法は
   "PyImport_ReloadModule()" を参照してください。

   *name* が "package.module" 形式のドット名表記であった場合、まだ作成
   されていないパッケージ構造はその作成されないままになります。

   "PyImport_ExecCodeModuleEx()" と
   "PyImport_ExecCodeModuleWithPathnames()" も参照してください。

PyObject *PyImport_ExecCodeModuleEx(const char *name, PyObject *co, const char *pathname)
    *Return value: New reference.** Part of the Stable ABI.*

   "PyImport_ExecCodeModule()" と似ていますが、*pathname* が "NULL" で
   ない場合にモジュールオブジェクトの "__file__" 属性に *pathname* が
   設定される点が異なります。

   "PyImport_ExecCodeModuleWithPathnames()" も参照してください。

PyObject *PyImport_ExecCodeModuleObject(PyObject *name, PyObject *co, PyObject *pathname, PyObject *cpathname)
    *Return value: New reference.** Part of the Stable ABI since
   version 3.7.*

   "PyImport_ExecCodeModuleEx()" と似ていますが、*cpathname* が "NULL"
   でない場合にモジュールオブジェクトの "__cached__" 属性に
   *cpathname* が設定される点が異なります。これらの 3 つの関数のうち、
   この関数の使用が望ましいです。

   バージョン 3.3 で追加.

PyObject *PyImport_ExecCodeModuleWithPathnames(const char *name, PyObject *co, const char *pathname, const char *cpathname)
    *Return value: New reference.** Part of the Stable ABI.*

   "PyImport_ExecCodeModuleObject()" と似ていますが、 *name* と
   *pathname*、 *cpathname* が UTF-8 でエンコードされた文字列である点
   が異なります。もし *pathname* が "NULL" の場合、*cpathname* から、
   *pathname* どのような値になるべきかを知る試みもなされます。

   バージョン 3.2 で追加.

   バージョン 3.3 で変更: バイトコードのパスが与えられた場合にのみ
   "imp.source_from_cache()" がソースパスの計算に使用されます。

long PyImport_GetMagicNumber()
    * Part of the Stable ABI.*

   Python バイトコードファイル (別名 ".pyc" ファイル) のマジックナンバ
   ーを返します。マジックナンバーはバイトコードファイルの最初の4バイト
   に、リトルエンディアンバイトオーダーで現れるべきです。エラーの場合
   は "-1" を返します。

   バージョン 3.3 で変更: 失敗した場合は "-1" の値を返します。

const char *PyImport_GetMagicTag()
    * Part of the Stable ABI.*

   マジックタグ文字列を Python バイトコードファイル名の **PEP 3147**
   フォーマットで返します。"sys.implementation.cache_tag" の値が信頼で
   き、かつこの関数の代わりに使用すべきであることを肝に命じましょう。

   バージョン 3.2 で追加.

PyObject *PyImport_GetModuleDict()
    *Return value: Borrowed reference.** Part of the Stable ABI.*

   モジュール管理のための辞書 (いわゆる "sys.modules")を返します。この
   辞書はインタプリタごとに一つだけある変数なので注意してください。

PyObject *PyImport_GetModule(PyObject *name)
    *Return value: New reference.** Part of the Stable ABI since
   version 3.8.*

   与えられた名前の既にインポート済みのモジュールを返します。 モジュー
   ルがインポートされていなかった場合は、 "NULL" を返しますが、エラー
   はセットしません。 モジュールの検索に失敗した場合は、 "NULL" を返し
   、エラーをセットします。

   バージョン 3.7 で追加.

PyObject *PyImport_GetImporter(PyObject *path)
    *Return value: New reference.** Part of the Stable ABI.*

   "sys.path" もしくは "pkg.__path__" の要素である *path* を見付けるた
   めのオブジェクトを返します。場合によっては
   "sys.path_importer_cache" 辞書から取得することもあります。 もしまだ
   オブジェクトがキャッシュされていなかった場合は、 path 要素を扱える
   フックが見付かるまで "sys.path_hooks" を走査します。 どのフックも
   path 要素を扱えない場合は "None" を返します; これにより、 *path
   based finder* がこの path 要素を見付けるためのオブジェクトが得られ
   なかったことを呼び出し元に伝えます。 最終的に得られたオブジェクトを
   "sys.path_importer_cache" へキャッシュし、オブジェクトへの新たな参
   照を返します。

int PyImport_ImportFrozenModuleObject(PyObject *name)
    * Part of the Stable ABI since version 3.7.*

   *name* という名前のフリーズ (freeze) されたモジュールをロードします
   。成功すると "1" を、モジュールが見つからなかった場合には "0" を、
   初期化が失敗した場合には例外をセットして "-1" を返します。ロードに
   成功したモジュールにアクセスするには "PyImport_ImportModule()" を使
   ってください。 (Note この関数はいささか誤解を招く名前です --- この
   関数はモジュールがすでにインポートされていたらリロードしてしまいま
   す。)

   バージョン 3.3 で追加.

   バージョン 3.4 で変更: "__file__" 属性はもうモジュールにセットされ
   ません。

int PyImport_ImportFrozenModule(const char *name)
    * Part of the Stable ABI.*

   "PyImport_ImportFrozenModuleObject()" と似ていますが、name は UTF-8
   でエンコードされた文字列の代わりに、 Unicode オブジェクトを使用する
   点が異なります。

struct _frozen

   **freeze** ユーティリティが生成するようなフリーズ化モジュールデスク
   リプタの構造体型定義です。 (Python ソース配布物の "Tools/freeze/"
   を参照してください) この構造体の定義は "Include/import.h" にあり、
   以下のようになっています:

      struct _frozen {
          const char *name;
          const unsigned char *code;
          int size;
      };

const struct _frozen *PyImport_FrozenModules

   このポインタは "_frozen" のレコードからなり、終端の要素のメンバが
   "NULL" かゼロになっているような配列を指すよう初期化されます。 フリ
   ーズされたモジュールをインポートするとき、このテーブルを検索します
   。 サードパーティ製のコードからこのポインタに仕掛けを講じて、動的に
   生成されたフリーズ化モジュールの集合を提供するようにできます。

int PyImport_AppendInittab(const char *name, PyObject *(*initfunc)(void))
    * Part of the Stable ABI.*

   既存の組み込みモジュールテーブルに単一のモジュールを追加します。こ
   の関数は利便性を目的とした "PyImport_ExtendInittab()" のラッパー関
   数で、テーブルが拡張できないときには "-1" を返します。新たなモジュ
   ールは *name* でインポートでき、最初にインポートを試みた際に呼び出
   される関数として *initfunc* を使います。 "Py_Initialize()" よりも前
   に呼び出さなければなりません。

struct _inittab

   組み込みモジュールリスト内の一つのエントリを記述している構造体です
   。リスト内の各構造体には、インタプリタ内に組み込まれているモジュー
   ルの名前と初期化関数が指定されています。 Python を埋め込むようなプ
   ログラムは、この構造体の配列と "PyImport_ExtendInittab()" を組み合
   わせて、追加の組み込みモジュールを提供できます。構造体は
   "Include/import.h" で以下のように定義されています:

      struct _inittab {
          const char *name;           /* ASCII encoded string */
          PyObject* (*initfunc)(void);
      };

int PyImport_ExtendInittab(struct _inittab *newtab)

   組み込みモジュールのテーブルに一群のモジュールを追加します。 配列
   *newtab* は "name" フィールドが "NULL" になっているセンチネル
   (sentinel) エントリで終端されていなければなりません。センチネル値を
   与えられなかった場合にはメモリ違反になるかもしれません。 成功すると
   "0" を、内部テーブルを拡張するのに十分なメモリを確保できなかった場
   合には "-1" を返します。 操作が失敗した場合、モジュールは一切内部テ
   ーブルに追加されません。 "Py_Initialize()" よりも前に呼び出さなけれ
   ばなりません。

   Python が複数回初期化される場合、"PyImport_AppendInittab()" または
   "PyImport_ExtendInittab()" は、それぞれの初期化の前に呼び出される必
   要があります。
