Importing Modules¶

PyObject*PyImport_ImportModule(constchar*name)¶

Return value: New reference. Part of theStable ABI.

This is a wrapper aroundPyImport_Import() which takes aconstchar* as an argument instead of aPyObject*.

PyObject*PyImport_ImportModuleNoBlock(constchar*name)¶

Return value: New reference. Part of theStable ABI.

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.

Deprecated since version 3.13, will be removed in version 3.15:UsePyImport_ImportModule() instead.

PyObject*PyImport_ImportModuleEx(constchar*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,intlevel)¶

Return value: New reference. Part of theStable ABI since version 3.7.

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.

Added in version 3.3.

PyObject*PyImport_ImportModuleLevel(constchar*name,PyObject*globals,PyObject*locals,PyObject*fromlist,intlevel)¶

Return value: New reference. Part of theStable ABI.

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. Part of theStable ABI.

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. Part of theStable ABI.

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_AddModuleRef(constchar*name)¶

Return value: New reference. Part of theStable ABI since version 3.13.

Return the module object corresponding to a module name.

Thename argument may be of the formpackage.module. First check themodules dictionary if there’s one there, and if not, create a new one andinsert it in the modules dictionary.

Return astrong reference to the module on success. ReturnNULLwith an exception set on failure.

The module namename is decoded from UTF-8.

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

Added in version 3.13.

PyObject*PyImport_AddModuleObject(PyObject*name)¶

Return value: Borrowed reference. Part of theStable ABI since version 3.7.

Similar toPyImport_AddModuleRef(), but return aborrowedreference andname is a Pythonstr object.

Added in version 3.3.

PyObject*PyImport_AddModule(constchar*name)¶

Return value: Borrowed reference. Part of theStable ABI.

Similar toPyImport_AddModuleRef(), but return aborrowedreference.

PyObject*PyImport_ExecCodeModule(constchar*name,PyObject*co)¶

Return value: New reference. Part of theStable ABI.

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 beset, if not set already, with the appropriate values. The spec’s loaderwill be set to the module’s__loader__ (if set) and to an instanceofSourceFileLoader otherwise.

The module’s__file__ attribute will be set to the codeobject’sco_filename. If applicable,__cached__ will also be 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().

Changed in version 3.12:The setting of__cached__ and__loader__is deprecated. SeeModuleSpec foralternatives.

PyObject*PyImport_ExecCodeModuleEx(constchar*name,PyObject*co,constchar*pathname)¶

Return value: New reference. Part of theStable ABI.

LikePyImport_ExecCodeModule(), but the__file__attribute of the 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. Part of theStable ABI since version 3.7.

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.

Added in version 3.3.

Changed in version 3.12:Setting__cached__ is deprecated. SeeModuleSpec for alternatives.

PyObject*PyImport_ExecCodeModuleWithPathnames(constchar*name,PyObject*co,constchar*pathname,constchar*cpathname)¶

Return value: New reference. Part of theStable ABI.

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.

Added in version 3.2.

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

Changed in version 3.12:No longer uses the removedimp module.

longPyImport_GetMagicNumber()¶

Part of theStable ABI.

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.

constchar*PyImport_GetMagicTag()¶

Part of theStable ABI.

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.

Added in version 3.2.

PyObject*PyImport_GetModuleDict()¶

Return value: Borrowed reference. Part of theStable ABI.

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. Part of theStable ABI since version 3.8.

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.

Added in version 3.7.

PyObject*PyImport_GetImporter(PyObject*path)¶

Return value: New reference. Part of theStable ABI.

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.

intPyImport_ImportFrozenModuleObject(PyObject*name)¶

Part of theStable ABI since version 3.7.

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

Added in version 3.3.

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

intPyImport_ImportFrozenModule(constchar*name)¶

Part of theStable ABI.

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;boolis_package;};

Changed in version 3.11:The newis_package field indicates whether the module is a package or not.This replaces setting thesize field to a negative value.

conststruct_frozen*PyImport_FrozenModules¶

This pointer is initialized to point to an array of_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(constchar*name,PyObject*(*initfunc)(void))¶

Part of theStable ABI.

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.Programs whichembed Python may use an array of these structures in conjunction withPyImport_ExtendInittab() to provide additional built-in modules.The structure consists of two members:

constchar*name¶

The module name, as an ASCII encoded string.

PyObject*(*initfunc)(void)¶

Initialization function for a module built into the interpreter.

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 must be called beforePy_Initialize().

If Python is initialized multiple times,PyImport_AppendInittab() orPyImport_ExtendInittab() must be called before each Pythoninitialization.

PyObject*PyImport_ImportModuleAttr(PyObject*mod_name,PyObject*attr_name)¶

Return value: New reference.

Import the modulemod_name and get its attributeattr_name.

Names must be Pythonstr objects.

Helper function combiningPyImport_Import() andPyObject_GetAttr(). For example, it can raiseImportError ifthe module is not found, andAttributeError if the attribute doesn’texist.

Added in version 3.14.

PyObject*PyImport_ImportModuleAttrString(constchar*mod_name,constchar*attr_name)¶

Return value: New reference.

Similar toPyImport_ImportModuleAttr(), but names are UTF-8 encodedstrings instead of Pythonstr objects.

Added in version 3.14.