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

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

  This is a wrapper around `PyImport_Import()` which takes a const char* as an argument instead of a PyObject*.

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

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

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

  Deprecated since version 3.13, will be removed in version 3.15: Use `PyImport_ImportModule()` instead.

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.

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

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

  Return the module object corresponding to a module name.

  The name argument may be of the form `package.module`. First check the modules dictionary if there's one there, and if not, create a new one and insert it in the modules dictionary.

  Return a strong reference to the module on success. Return `NULL` with an exception set on failure.

  The module name name is decoded from UTF-8.

  This function does not load or import the module; if the module wasn't already loaded, you will get an empty module object. Use `PyImport_ImportModule()` or one of its variants to import a module. Package structures implied by a dotted name for name are not created if not already present.

  Added in version 3.13.

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

  Similar to `PyImport_AddModuleRef()`, but return a borrowed reference and name is a Python `str` object.

  Added in version 3.3.

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

  Similar to `PyImport_AddModuleRef()`, but return a borrowed reference.

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

  Given a module name (possibly of the form `package.module`) and a code object read from a Python bytecode file or obtained from the built-in function `compile()`, load the module. Return a new reference to the module object, or `NULL` with an exception set if an error occurred. name is removed from `sys.modules` in error cases, even if name was already in `sys.modules` on entry to `PyImport_ExecCodeModule()`. Leaving incompletely initialized modules in `sys.modules` is dangerous, as imports of such modules have no way to know that the module object is an unknown (and probably damaged with respect to the module author's intents) state.

  The module's `__spec__` and `__loader__` will be set, if not set already, with the appropriate values. The spec's loader will be set to the module's `__loader__` (if set) and to an instance of `SourceFileLoader` otherwise.

  The module's `__file__` attribute will be set to the code object's `co_filename`. If applicable, `__cached__` will also be set.

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

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

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

  バージョン 3.12 で変更: The setting of `__cached__` and `__loader__` is deprecated. See `ModuleSpec` for alternatives.

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

  Like `PyImport_ExecCodeModule()`, but the `__file__` attribute of the module object is set to pathname if it is non-`NULL`.

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

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

  Like `PyImport_ExecCodeModuleEx()`, but the `__cached__` attribute of the module object is set to cpathname if it is non-`NULL`. Of the three functions, this is the preferred one to use.

  Added in version 3.3.

  バージョン 3.12 で変更: Setting `__cached__` is deprecated. See `ModuleSpec` for alternatives.

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 で変更: Uses `imp.source_from_cache()` in calculating the source path if only the bytecode path is provided.

  バージョン 3.12 で変更: No longer uses the removed `imp` module.

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.

  Return a finder object for a `sys.path`/`pkg.__path__` item path, possibly by fetching it from the `sys.path_importer_cache` dict. If it wasn't yet cached, traverse `sys.path_hooks` until a hook is found that can handle the path item. Return `None` if no hook could; this tells our caller that the path based finder could not find a finder for this path item. Cache the result in `sys.path_importer_cache`. Return a new reference to the finder object.

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

struct _frozen

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

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

  バージョン 3.11 で変更: The new `is_package` field indicates whether the module is a package or not. This replaces setting the `size` field to a negative value.

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

  Structure describing a single entry in the list of built-in modules. Programs which embed Python may use an array of these structures in conjunction with `PyImport_ExtendInittab()` to provide additional built-in modules. The structure consists of two members:

  const char *name

    The module name, as an ASCII encoded string.

  PyObject *(*initfunc)(void)

    Initialization function for a module built into the interpreter.

int PyImport_ExtendInittab(struct _inittab *newtab)

  Add a collection of modules to the table of built-in modules. The newtab array must end with a sentinel entry which contains `NULL` for the `name` field; failure to provide the sentinel value can result in a memory fault. Returns `0` on success or `-1` if insufficient memory could be allocated to extend the internal table. In the event of failure, no modules are added to the internal table. This must be called before `Py_Initialize()`.

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

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

  Import the module mod_name and get its attribute attr_name.

  Names must be Python `str` objects.

  Helper function combining `PyImport_Import()` and `PyObject_GetAttr()`. For example, it can raise `ImportError` if the module is not found, and `AttributeError` if the attribute doesn't exist.

  Added in version 3.14.

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

  Similar to `PyImport_ImportModuleAttr()`, but names are UTF-8 encoded strings instead of Python `str` objects.

  Added in version 3.14.