#
5.3 Importing Modules

PyObject* `PyImport_ImportModule` (char *name)
  Return value: New reference.
  This is a simplified interface to `PyImport_ImportModuleEx()` below, leaving the globals and locals arguments set to `NULL`. When the name argument contains a dot (i.e., 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 (the module may still be created in this case -- examine `sys.modules` to find out).

PyObject* `PyImport_ImportModuleEx` (char *name, PyObject *globals, PyObject *locals, PyObject *fromlist)
  Return value: New reference.
  Import a module. This is best described by referring to the built-in Python function `__import__()`, as the standard `__import__()` function calls this function directly.

  The return value is a new reference to the imported module or top-level package, or `NULL` with an exception set on failure (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.

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`.

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` (char *name)
  Return value: Borrowed reference.
  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 in in the modules dictionary. Warning: 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. Return `NULL` with an exception set on failure.

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 (the module may still be created in this case). (This function would reload the module if it was already imported.)

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.
  Return the dictionary used for the module administration (a.k.a. `sys.modules`). Note that this is a per-interpreter variable.

void `_PyImport_Init` ()
  Initialize the import mechanism. For internal use only.

void `PyImport_Cleanup` ()
  Empty the module table. For internal use only.

void `_PyImport_Fini` ()
  Finalize the import mechanism. For internal use only.

PyObject* `_PyImport_FindExtension` (char *, char *)
  Return value: Borrowed reference.
  For internal use only.

PyObject* `_PyImport_FixupExtension` (char *, char *)
  For internal use only.

int `PyImport_ImportFrozenModule` (char *)
  Load a frozen module. Return `1` for success, `0` if the module is not found, and `-1` with an exception set if the initialization failed. To access the imported module on a successful load, use `PyImport_ImportModule()`. (Note the misnomer -- this function would reload the module if it was already imported.)

`struct _frozen`
  This is the structure type definition for frozen module descriptors, as generated by the freeze utility (see Tools/freeze/ in the Python source distribution). Its definition is:

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

struct _frozen* `PyImport_FrozenModules`
  This pointer is initialized to point to an array of `struct _frozen` records, terminated by one whose members are all `NULL` or zero. When a frozen module is imported, it is searched in this table. Third-party code could play tricks with this to provide a dynamically created collection of frozen modules.