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

PyObject* PyImport_ImportModule(const char *name)
    *Return value: New reference.*

   This is a simplified interface to "PyImport_ImportModuleEx()"
   below, leaving the *globals* and *locals* arguments set to *NULL*
   and *level* set to 0.  When the *name* argument contains a dot
   (when it specifies a submodule of a package), the *fromlist*
   argument is set to the list "['*']" so that the return value is the
   named module rather than the top-level package containing it as
   would otherwise be the case.  (Unfortunately, this has an
   additional side effect when *name* in fact specifies a subpackage
   instead of a submodule: the submodules specified in the package’s
   "__all__" variable are  loaded.)  Return a new reference to the
   imported module, or *NULL* with an exception set on failure.
   Before Python 2.4, the module may still be created in the failure
   case — examine "sys.modules" to find out.  Starting with Python
   2.4, a failing import of a module no longer leaves the module in
   "sys.modules".

   バージョン 2.4 で変更: Failing imports remove incomplete module
   objects.

   バージョン 2.6 で変更: Always uses absolute imports.

PyObject* PyImport_ImportModuleNoBlock(const char *name)

   This version of "PyImport_ImportModule()" does not block. It’s
   intended to be used in C functions that import other modules to
   execute a function. The import may block if another thread holds
   the import lock. The function "PyImport_ImportModuleNoBlock()"
   never blocks. It first tries to fetch the module from sys.modules
   and falls back to "PyImport_ImportModule()" unless the lock is
   held, in which case the function will raise an "ImportError".

   バージョン 2.6 で追加.

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

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

   The return value is a new reference to the imported module or top-
   level package, or *NULL* with an exception set on failure (before
   Python 2.4, the module may still be created in this case).  Like
   for "__import__()", the return value when a submodule of a package
   was requested is normally the top-level package, unless a non-empty
   *fromlist* was given.

   バージョン 2.4 で変更: Failing imports remove incomplete module
   objects.

   バージョン 2.6 で変更: The function is an alias for
   "PyImport_ImportModuleLevel()" with "-1" as level, meaning relative
   import.

PyObject* PyImport_ImportModuleLevel(char *name, PyObject *globals, PyObject *locals, PyObject *fromlist, int level)
    *Return value: New reference.*

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

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

   バージョン 2.5 で追加.

PyObject* PyImport_Import(PyObject *name)
    *Return value: New reference.*

   This is a higher-level interface that calls the current 「import
   hook function」. It invokes the "__import__()" function from the
   "__builtins__" of the current globals.  This means that the import
   is done using whatever import hooks are installed in the current
   environment, e.g. by "rexec" or "ihooks".

   バージョン 2.6 で変更: Always uses absolute imports.

PyObject* PyImport_ReloadModule(PyObject *m)
    *Return value: New reference.*

   Reload a module.  This is best described by referring to the built-
   in Python function "reload()", as the standard "reload()" function
   calls this function directly.  Return a new reference to the
   reloaded module, or *NULL* with an exception set on failure (the
   module still exists in this case).

PyObject* PyImport_AddModule(const char *name)
    *Return value: Borrowed reference.*

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

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

PyObject* PyImport_ExecCodeModule(char *name, PyObject *co)
    *Return value: New reference.*

   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.  Before Python 2.4, the module could still be
   created in error cases.  Starting with Python 2.4, *name* is
   removed from "sys.modules" in error cases, and 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 "__file__" attribute will be set to the code object’s
   "co_filename".

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

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

   バージョン 2.4 で変更: *name* is removed from "sys.modules" in
   error cases.

PyObject* PyImport_ExecCodeModuleEx(char *name, PyObject *co, char *pathname)
    *Return value: New reference.*

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

long PyImport_GetMagicNumber()

   Return the magic number for Python bytecode files (a.k.a. ".pyc"
   and ".pyo" files).  The magic number should be present in the first
   four bytes of the bytecode file, in little-endian byte order.

PyObject* PyImport_GetModuleDict()
    *Return value: Borrowed reference.*

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

PyObject* PyImport_GetImporter(PyObject *path)

   Return an importer 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 it should fall back to the built-
   in import mechanism. Cache the result in "sys.path_importer_cache".
   Return a new reference to the importer object.

   バージョン 2.6 で追加.

void _PyImport_Init()

   インポート機構を初期化します。内部使用だけのための関数です。

void PyImport_Cleanup()

   モジュールテーブルを空にします。内部使用だけのための関数です。

void _PyImport_Fini()

   インポート機構を終了処理します。内部使用だけのための関数です。

PyObject* _PyImport_FindExtension(char *, char *)

   内部使用だけのための関数です。

PyObject* _PyImport_FixupExtension(char *, char *)

   内部使用だけのための関数です。

int PyImport_ImportFrozenModule(char *name)

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

struct _frozen

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

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

struct _frozen* PyImport_FrozenModules

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

int PyImport_AppendInittab(const char *name, void (*initfunc)(void))

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

struct _inittab

   Structure describing a single entry in the list of built-in
   modules.  Each of these structures gives the name and
   initialization function for a module built into the interpreter.
   Programs which embed Python may use an array of these structures in
   conjunction with "PyImport_ExtendInittab()" to provide additional
   built-in modules.  The structure is defined in "Include/import.h"
   as:

      struct _inittab {
          char *name;
          void (*initfunc)(void);
      };

int PyImport_ExtendInittab(struct _inittab *newtab)

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