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

PyObject *PyImport_ImportModule(const char *name)
    *戻り値: 新しい参照。** 次に属します: Stable ABI.*

   "PyImport_Import()" のラッパーで、引数として PyObject* の代わりに
   const char* を受け取ります。

PyObject *PyImport_ImportModuleEx(const char *name, PyObject *globals, PyObject *locals, PyObject *fromlist)
    *戻り値: 新しい参照。*

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

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

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

PyObject *PyImport_ImportModuleLevelObject(PyObject *name, PyObject *globals, PyObject *locals, PyObject *fromlist, int level)
    *戻り値: 新しい参照。** 次に属します: Stable ABI (バージョン 3.7
   より).*

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

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

   Added in version 3.3.

PyObject *PyImport_ImportModuleLevel(const char *name, PyObject *globals, PyObject *locals, PyObject *fromlist, int level)
    *戻り値: 新しい参照。** 次に属します: Stable ABI.*

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

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

PyObject *PyImport_Import(PyObject *name)
    *戻り値: 新しい参照。** 次に属します: Stable ABI.*

   現在の「インポートフック関数」を呼び出す高水準のインターフェースで
   す ("level" は明示的に 0、つまり絶対インポートに設定されます)。 現
   在のグローバル名前空間の "__builtins__" から "__import__()" 関数を
   呼び出します。 したがって、現在の環境にインストールされたインポート
   フックを使ってインポートします。

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

PyObject *PyImport_ReloadModule(PyObject *m)
    *戻り値: 新しい参照。** 次に属します: Stable ABI.*

   モジュールを再読み込みします。 再読み込みしたモジュールへの新しい参
   照を返します。 失敗した場合は例外を設定して "NULL" を返します (この
   場合もモジュールは存在します)。

PyObject *PyImport_AddModuleRef(const char *name)
    *戻り値: 新しい参照。** 次に属します: Stable ABI (バージョン 3.13
   より).*

   モジュール名に対応するモジュールオブジェクトを返します。

   "name" 引数は "package.module" という形式でも構いません。 まずモジ
   ュール辞書内を確認し、該当するモジュールがなければ新しく作成してモ
   ジュール辞書に挿入します。

   成功した場合はモジュールへの *強参照* を返します。 失敗した場合は例
   外を設定して "NULL" を返します。

   モジュール名 "name" は UTF-8 からデコードされます。

   この関数はモジュールを読み込んだりインポートしたりしません。 モジュ
   ールがまだ読み込まれていない場合は、空のモジュールオブジェクトが返
   されます。 モジュールをインポートするには "PyImport_ImportModule()"
   またはその変種を使ってください。 "name" がドットで区切られた名前で
   あっても、まだ存在しないパッケージ構造は作成されません。

   Added in version 3.13.

PyObject *PyImport_AddModuleObject(PyObject *name)
    *戻り値: 借用参照。** 次に属します: Stable ABI (バージョン 3.7 よ
   り).*

   "PyImport_AddModuleRef()" と同様ですが、*借用参照* を返し、"name"
   は Python の "str" オブジェクトです。

   Added in version 3.3.

PyObject *PyImport_AddModule(const char *name)
    *戻り値: 借用参照。** 次に属します: Stable ABI.*

   "PyImport_AddModuleRef()" と同様ですが、*借用参照* を返します。

PyObject *PyImport_ExecCodeModule(const char *name, PyObject *co)
    *戻り値: 新しい参照。** 次に属します: Stable ABI.*

   モジュール名 ("package.module" 形式でも可) と、Python バイトコード
   ファイルから読み込んだか組み込み関数 "compile()" で取得したコードオ
   ブジェクトを使って、モジュールを読み込みます。 モジュールオブジェク
   トへの新しい参照を返し、エラーの場合は例外を設定して "NULL" を返し
   ます。 エラーの場合、"PyImport_ExecCodeModule()" の呼び出し時に
   "name" がすでに "sys.modules" に存在していたとしても、"sys.modules"
   から "name" を削除します。 不完全に初期化されたモジュールを
   "sys.modules" に残すのは危険です。 そのモジュールをインポートする側
   には、モジュールオブジェクトが不明な状態 (おそらく作者の意図からす
   れば壊れた状態) にあると知る手段がないためです。

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

   モジュールの "__file__" 属性には、コードオブジェクトの
   "co_filename" を設定します。

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

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

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

   バージョン 3.12 で変更: "__cached__" と "__loader__" の設定は非推奨
   になりました。 代替については "ModuleSpec" を参照してください。

   バージョン 3.15 で変更: "__cached__" 属性を設定しなくなりました。

PyObject *PyImport_ExecCodeModuleEx(const char *name, PyObject *co, const char *pathname)
    *戻り値: 新しい参照。** 次に属します: Stable ABI.*

   "PyImport_ExecCodeModule()" と同様ですが、"pathname" が "NULL" でな
   ければモジュールオブジェクトの "__file__" 属性をその値に設定します
   。

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

PyObject *PyImport_ExecCodeModuleObject(PyObject *name, PyObject *co, PyObject *pathname, PyObject *cpathname)
    *戻り値: 新しい参照。** 次に属します: Stable ABI (バージョン 3.7
   より).*

   "PyImport_ExecCodeModuleEx()" と同様ですが、"cpathname" が "NULL"
   でなければ、そこで指定されたコンパイル済みファイルのパスを適切に使
   います。 三つの関数の中では、この関数の使用を推奨します。

   Added in version 3.3.

   バージョン 3.12 で変更: "__cached__" の設定は非推奨になりました。
   代替については "ModuleSpec" を参照してください。

   バージョン 3.15 で変更: "__cached__" 属性を設定しなくなりました。

PyObject *PyImport_ExecCodeModuleWithPathnames(const char *name, PyObject *co, const char *pathname, const char *cpathname)
    *戻り値: 新しい参照。** 次に属します: Stable ABI.*

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

   Added in version 3.2.

   バージョン 3.3 で変更: バイトコードのパスだけが指定された場合、ソー
   スのパスの計算に "imp.source_from_cache()" を使います。

   バージョン 3.12 で変更: 削除された "imp" モジュールを使わなくなりま
   した。

long PyImport_GetMagicNumber()
    * 次に属します: Stable ABI.*

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

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

const char *PyImport_GetMagicTag()
    * 次に属します: Stable ABI.*

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

   Added in version 3.2.

PyObject *PyImport_GetModuleDict()
    *戻り値: 借用参照。** 次に属します: Stable ABI.*

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

PyObject *PyImport_GetModule(PyObject *name)
    *戻り値: 新しい参照。** 次に属します: Stable ABI (バージョン 3.8
   より).*

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

   Added in version 3.7.

PyObject *PyImport_GetImporter(PyObject *path)
    *戻り値: 新しい参照。** 次に属します: Stable ABI.*

   "sys.path" または "pkg.__path__" の要素 "path" に対応するファインダ
   ーオブジェクトを返します。 "sys.path_importer_cache" 辞書から取得す
   る場合もあります。 まだキャッシュされていなければ、そのパス要素を扱
   えるフックが見つかるまで "sys.path_hooks" を順に調べます。 どのフッ
   クも扱えない場合は "None" を返し、*パスベースのファインダー* がこの
   パス要素のファインダーを見つけられなかったことを呼び出し側に伝えま
   す。 結果は "sys.path_importer_cache" にキャッシュします。 ファイン
   ダーオブジェクトへの新しい参照を返します。

int PyImport_ImportFrozenModuleObject(PyObject *name)
    * 次に属します: Stable ABI (バージョン 3.7 より).*

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

   Added in version 3.3.

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

int PyImport_ImportFrozenModule(const char *name)
    * 次に属します: Stable ABI.*

   "PyImport_ImportFrozenModuleObject()" と同様ですが、名前は Unicode
   オブジェクトではなく UTF-8 エンコードの文字列です。

struct _frozen

   **freeze** ユーティリティ (Python ソース配布物の "Tools/freeze/" を
   参照) が生成する、フリーズされたモジュールの記述子の構造体型です。
   "Include/import.h" にある定義は次のとおりです。

      struct _frozen {
          const char *name;                 /* ASCII エンコードの文字列 */
          const unsigned char *code;
          int size;
          int is_package;
      };

   バージョン 3.11 で変更: 新しい "is_package" フィールドは、モジュー
   ルがパッケージかどうかを示します。 "size" フィールドを負の値に設定
   する方法に代わるものです。

const struct _frozen *PyImport_FrozenModules

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

int PyImport_AppendInittab(const char *name, PyObject *(*initfunc)(void))
    * 次に属します: Stable ABI.*

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

struct _inittab

   組み込みモジュールの一覧の一つのエントリーを記述する構造体です。
   Python を組み込むプログラムは、この構造体の配列を
   "PyImport_ExtendInittab()" と併用して、追加の組み込みモジュールを提
   供できます。 構造体は二つのメンバからなります。

   const char *name

      ASCII エンコードの文字列で表したモジュール名。

   PyObject *(*initfunc)(void)

      インタープリタに組み込まれたモジュールの初期化関数。

      inittab は「"PyInit"」の 初期化関数 を使います。 現在、「
      "PyModExport_"」の エクスポートフック を含める方法はありません。

int PyImport_ExtendInittab(struct _inittab *newtab)

   組み込みモジュールのテーブルに、複数のモジュールを追加します。
   "newtab" 配列は、"name" フィールドが "NULL" の番兵エントリーで終わ
   る必要があります。 番兵がないとメモリアクセス違反を引き起こす可能性
   があります。 成功した場合は "0" を返し、内部テーブルを拡張するため
   のメモリを十分に割り当てられなければ "-1" を返します。 失敗した場合
   、内部テーブルにモジュールは一つも追加されません。
   "Py_Initialize()" より前に呼び出す必要があります。

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

struct _inittab *PyImport_Inittab

   Python の初期化で使う組み込みモジュールのテーブルです。 直接使わず
   、代わりに "PyImport_AppendInittab()" と "PyImport_ExtendInittab()"
   を使ってください。

PyObject *PyImport_ImportModuleAttr(PyObject *mod_name, PyObject *attr_name)
    *戻り値: 新しい参照。*

   モジュール "mod_name" をインポートし、その属性 "attr_name" を取得し
   ます。

   名前は Python の "str" オブジェクトでなければなりません。

   "PyImport_Import()" と "PyObject_GetAttr()" を組み合わせた補助関数
   です。 例えば、モジュールが見つからなければ "ImportError"、属性が存
   在しなければ "AttributeError" を送出することがあります。

   Added in version 3.14.

PyObject *PyImport_ImportModuleAttrString(const char *mod_name, const char *attr_name)
    *戻り値: 新しい参照。*

   "PyImport_ImportModuleAttr()" と同様ですが、名前は Python の "str"
   オブジェクトではなく UTF-8 エンコードの文字列です。

   Added in version 3.14.

PyImport_LazyImportsMode PyImport_GetLazyImportsMode()

   現在の遅延インポートモードを取得します。

   Added in version 3.15.

PyObject *PyImport_GetLazyImportsFilter()

   現在の遅延インポートフィルタへの *強参照* を返します。 フィルタがな
   ければ "NULL" を返します。 この関数は常に成功します。

   Added in version 3.15.

int PyImport_SetLazyImportsMode(PyImport_LazyImportsMode mode)

   現在の遅延インポートモードを設定します。

   この関数は常に "0" を返します。

   Added in version 3.15.

int PyImport_SetLazyImportsFilter(PyObject *filter)

   現在の遅延インポートフィルタを設定します。 "filter" には、インポー
   トを遅延できる可能性があるときに "(importing_module_name,
   imported_module_name, [fromlist])" を受け取る呼び出し可能オブジェク
   トを指定してください。 "imported_module_name" は解決済みのモジュー
   ル名なので、"lazy from .spam import eggs" の場合は "package.spam"
   が渡されます。 この呼び出し可能オブジェクトは、インポートを遅延すべ
   きなら "True"、そうでなければ "False" を返す必要があります。

   成功した場合は "0" を返し、それ以外の場合は例外を設定して "-1" を返
   します。

   Added in version 3.15.

type PyImport_LazyImportsMode

   遅延インポートモードの列挙型。

   enumerator PyImport_LAZY_NORMAL

      ソースコード内の "lazy" キーワードに従います。 デフォルトのモー
      ドです。

   enumerator PyImport_LAZY_ALL

      デフォルトですべてのインポートを遅延させます。

   Added in version 3.15.

PyObject *PyImport_CreateModuleFromInitfunc(PyObject *spec, PyObject *(*initfunc)(void))

   この関数は、Python を組み込む側が、静的拡張 (例えば静的リンクされた
   拡張) 用のカスタムインポータの "create_module()" ステップを実装する
   ための構成要素です。

   "spec" は "ModuleSpec" オブジェクトでなければなりません。

   "initfunc" は、"PyImport_AppendInittab()" と同じく 初期化関数 でな
   ければなりません。

   成功した場合は、モジュールオブジェクトを作成して返します。 このモジ
   ュールはまだ初期化されていないので、"PyModule_Exec()" を呼び出して
   初期化してください。 (カスタムインポータでは "exec_module()" メソッ
   ド内で行ってください。)

   エラーの場合は例外を設定して NULL を返します。

   従来の単相初期化 を使うモジュールでは、通常インポータが
   "create_module()" の後で行う追加のステップではなく、この関数内でイ
   ンポート処理の大半を行います。 具体的には次のとおりです。

   * 初期化の一環として、モジュールを "spec" の "name" の名前で
     "sys.modules" に追加します。

   * 同じ "name" の単相モジュールが、この関数または組み込みモジュール
     として (例えば "PyImport_AppendInittab()" で登録して) 以前にイン
     ポートされていた場合、Python は "initfunc" を再び呼ぶ代わりに、以
     前のモジュールの内容を再利用することがあります。

   * モジュールは "initfunc" によって完全に初期化されます。
     "PyModule_Exec()" を呼び出しても効果はありませんが、モジュールが
     将来 多相初期化 に移行した場合に備えて、呼び出すことを推奨します
     。

   * また、"spec" の "name" にドットが含まれる場合、この名前を使って新
     しいモジュールの "__name__" に親パッケージの名前を前置します。

   Added in version 3.15.
