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

PyObject *PyImport_ImportModule(const char *name)
    *Return value: New reference.** Part of the 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)
    *Return value: New reference.** Part of the Stable ABI.*

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

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

   バージョン 3.13 で非推奨、バージョン 3.15 で削除予定: Use
   "PyImport_ImportModule()" instead.

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_AddModuleRef(const char *name)
    *Return value: New reference.** Part of the Stable ABI since
   version 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.

   バージョン 3.13 で追加.

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

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

   バージョン 3.3 で追加.

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

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

PyObject *PyImport_ExecCodeModule(const char *name, PyObject *co)
    *Return value: New reference.** Part of the 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)
    *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 で追加.

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

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 で変更: 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()
    * 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.*

   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)
    * 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;
          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))
    * Part of the 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()" は、それぞれの初期化の前に呼び出される必
   要があります。
