# 5.2 Importing modules

PyObject * `PyImport_ImportModule`(char *name)
  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).

PyObject * `PyImport_ImportModuleEx`(char *name, PyObject *globals, PyObject *locals, PyObject *fromlist)
  (NEW in 1.5a4!) 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)
  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)
  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 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. Because the former action is most common, this does not return a new reference, and you do not own the returned reference. Return NULL with an exception set on failure.

PyObject * `PyImport_ExecCodeModule`(char *name, PyObject *co)
  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 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.

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

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