Importing Modules¶

PyObject*PyImport_ImportModule(const char *name)¶

Return value: New reference.

This is a simplified interface toPyImport_ImportModuleEx() below,leaving theglobals andlocals arguments set toNULL andlevel setto 0. When thenameargument contains a dot (when it specifies a submodule of a package), thefromlist argument is set to the list['*'] so that the return value is thenamed module rather than the top-level package containing it as would otherwisebe the case. (Unfortunately, this has an additional side effect whenname infact specifies a subpackage instead of a submodule: the submodules specified inthe package’s__all__ variable are loaded.) Return a new reference to theimported module, orNULL with an exception set on failure. A failingimport of a module doesn’t leave the module insys.modules.

This function always uses absolute imports.

PyObject*PyImport_ImportModuleNoBlock(const char *name)¶

Return value: New reference.

This function is a deprecated alias ofPyImport_ImportModule().

Changed in version 3.3:This function used to fail immediately when the import lock was heldby another thread. In Python 3.3 though, the locking scheme switchedto per-module locks for most purposes, so this function’s specialbehaviour isn’t needed anymore.

PyObject*PyImport_ImportModuleEx(const 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 Pythonfunction__import__().

The return value is a new reference to the imported module or top-levelpackage, orNULL with an exception set on failure. Like for__import__(), the return value when a submodule of a package wasrequested is normally the top-level package, unless a non-emptyfromlistwas given.

Failing imports remove incomplete module objects, like withPyImport_ImportModule().

PyObject*PyImport_ImportModuleLevelObject(PyObject *name,PyObject *globals,PyObject *locals,PyObject *fromlist, int level)¶

Return value: New reference.

Import a module. This is best described by referring to the built-in Pythonfunction__import__(), as the standard__import__() function callsthis function directly.

The return value is a new reference to the imported module or top-level package,orNULL with an exception set on failure. Like for__import__(),the return value when a submodule of a package was requested is normally thetop-level package, unless a non-emptyfromlist was given.

New in version 3.3.

PyObject*PyImport_ImportModuleLevel(const char *name,PyObject *globals,PyObject *locals,PyObject *fromlist, int level)¶

Return value: New reference.

Similar toPyImport_ImportModuleLevelObject(), but the name is aUTF-8 encoded string instead of a Unicode object.

Changed in version 3.3:Negative values forlevel are no longer accepted.

PyObject*PyImport_Import(PyObject *name)¶

Return value: New reference.

This is a higher-level interface that calls the current “import hookfunction” (with an explicitlevel of 0, meaning absolute import). Itinvokes the__import__() function from the__builtins__ of thecurrent globals. This means that the import is done using whatever importhooks are installed in the current environment.

This function always uses absolute imports.

PyObject*PyImport_ReloadModule(PyObject *m)¶

Return value: New reference.

Reload a module. Return a new reference to the reloaded module, orNULL withan exception set on failure (the module still exists in this case).

PyObject*PyImport_AddModuleObject(PyObject *name)¶

Return value: Borrowed reference.

Return the module object corresponding to a module name. Thename argumentmay be of the formpackage.module. First check the modules dictionary ifthere’s one there, and if not, create a new one and insert it in the modulesdictionary. ReturnNULL with an exception set on failure.

Note

This function does not load or import the module; if the module wasn’t alreadyloaded, you will get an empty module object. UsePyImport_ImportModule()or one of its variants to import a module. Package structures implied by adotted name forname are not created if not already present.

New in version 3.3.

PyObject*PyImport_AddModule(const char *name)¶

Return value: Borrowed reference.

Similar toPyImport_AddModuleObject(), but the name is a UTF-8encoded string instead of a Unicode object.

PyObject*PyImport_ExecCodeModule(const char *name,PyObject *co)¶

Return value: New reference.

Given a module name (possibly of the formpackage.module) and a code objectread from a Python bytecode file or obtained from the built-in functioncompile(), load the module. Return a new reference to the module object,orNULL with an exception set if an error occurred.nameis removed fromsys.modules in error cases, even ifname was alreadyinsys.modules on entry toPyImport_ExecCodeModule(). Leavingincompletely initialized modules insys.modules is dangerous, as imports ofsuch modules have no way to know that the module object is an unknown (andprobably damaged with respect to the module author’s intents) state.

The module’s__spec__ and__loader__ will be set, ifnot set already, with the appropriate values. The spec’s loader willbe set to the module’s__loader__ (if set) and to an instance ofSourceFileLoader otherwise.

The module’s__file__ attribute will be set to the code object’sco_filename. If applicable,__cached__ will alsobe set.

This function will reload the module if it was already imported. SeePyImport_ReloadModule() for the intended way to reload a module.

Ifname points to a dotted name of the formpackage.module, any packagestructures not already created will still not be created.

See alsoPyImport_ExecCodeModuleEx() andPyImport_ExecCodeModuleWithPathnames().

PyObject*PyImport_ExecCodeModuleEx(const char *name,PyObject *co, const char *pathname)¶

Return value: New reference.

LikePyImport_ExecCodeModule(), but the__file__ attribute ofthe module object is set topathname if it is non-NULL.

See alsoPyImport_ExecCodeModuleWithPathnames().

PyObject*PyImport_ExecCodeModuleObject(PyObject *name,PyObject *co,PyObject *pathname,PyObject *cpathname)¶

Return value: New reference.

LikePyImport_ExecCodeModuleEx(), but the__cached__attribute of the module object is set tocpathname if it isnon-NULL. Of the three functions, this is the preferred one to use.

New in version 3.3.

PyObject*PyImport_ExecCodeModuleWithPathnames(const char *name,PyObject *co, const char *pathname, const char *cpathname)¶

Return value: New reference.

LikePyImport_ExecCodeModuleObject(), butname,pathname andcpathname are UTF-8 encoded strings. Attempts are also made to figure outwhat the value forpathname should be fromcpathname if the former isset toNULL.

New in version 3.2.

Changed in version 3.3:Usesimp.source_from_cache() in calculating the source path ifonly the bytecode path is provided.

longPyImport_GetMagicNumber()¶

Return the magic number for Python bytecode files (a.k.a..pyc file).The magic number should be present in the first four bytes of the bytecodefile, in little-endian byte order. Returns-1 on error.

Changed in version 3.3:Return value of-1 upon failure.

const char *PyImport_GetMagicTag()¶

Return the magic tag string forPEP 3147 format Python bytecode filenames. Keep in mind that the value atsys.implementation.cache_tag isauthoritative and should be used instead of this function.

New in version 3.2.

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.

PyObject*PyImport_GetModule(PyObject *name)¶

Return value: New reference.

Return the already imported module with the given name. If themodule has not been imported yet then returnsNULL but does not setan error. ReturnsNULL and sets an error if the lookup failed.

New in version 3.7.

PyObject*PyImport_GetImporter(PyObject *path)¶

Return value: New reference.

Return a finder object for asys.path/pkg.__path__ itempath, possibly by fetching it from thesys.path_importer_cachedict. If it wasn’t yet cached, traversesys.path_hooks until a hookis found that can handle the path item. ReturnNone if no hook could;this tells our caller that thepath based finder could not find afinder for this path item. Cache the result insys.path_importer_cache.Return a new reference to the finder object.

void_PyImport_Init()¶

Initialize the import mechanism. For internal use only.

voidPyImport_Cleanup()¶

Empty the module table. For internal use only.

void_PyImport_Fini()¶

Finalize the import mechanism. For internal use only.

intPyImport_ImportFrozenModuleObject(PyObject *name)¶

Return value: New reference.

Load a frozen module namedname. Return1 for success,0 if themodule is not found, and-1 with an exception set if the initializationfailed. To access the imported module on a successful load, usePyImport_ImportModule(). (Note the misnomer — this function wouldreload the module if it was already imported.)

New in version 3.3.

Changed in version 3.4:The__file__ attribute is no longer set on the module.

intPyImport_ImportFrozenModule(const char *name)¶

Similar toPyImport_ImportFrozenModuleObject(), but the name is aUTF-8 encoded string instead of a Unicode object.

struct_frozen¶

This is the structure type definition for frozen module descriptors, asgenerated by thefreeze utility (seeTools/freeze/ in thePython source distribution). Its definition, found inInclude/import.h,is:

struct_frozen{constchar*name;constunsignedchar*code;intsize;};

const struct_frozen*PyImport_FrozenModules¶

This pointer is initialized to point to an array ofstruct_frozenrecords, terminated by one whose members are allNULL or zero. When a frozenmodule is imported, it is searched in this table. Third-party code could playtricks with this to provide a dynamically created collection of frozen modules.

intPyImport_AppendInittab(const char *name,PyObject* (*initfunc)(void))¶

Add a single module to the existing table of built-in modules. This is aconvenience wrapper aroundPyImport_ExtendInittab(), returning-1 ifthe table could not be extended. The new module can be imported by the namename, and uses the functioninitfunc as the initialization function calledon the first attempted import. This should be called beforePy_Initialize().

struct_inittab¶

Structure describing a single entry in the list of built-in modules. Each ofthese structures gives the name and initialization function for a module builtinto the interpreter. The name is an ASCII encoded string. Programs whichembed Python may use an array of these structures in conjunction withPyImport_ExtendInittab() to provide additional built-in modules.The structure is defined inInclude/import.h as:

struct_inittab{constchar*name;/* ASCII encoded string */PyObject*(*initfunc)(void);};

intPyImport_ExtendInittab(struct_inittab *newtab)¶

Add a collection of modules to the table of built-in modules. Thenewtabarray must end with a sentinel entry which containsNULL for thenamefield; failure to provide the sentinel value can result in a memory fault.Returns0 on success or-1 if insufficient memory could be allocated toextend the internal table. In the event of failure, no modules are added to theinternal table. This should be called beforePy_Initialize().