9 .. cfunction:: PyObject* PyImport_ImportModule(const char *name)
12 single: package variable; __all__
13 single: __all__ (package variable)
14 single: modules (in module sys)
16 This is a simplified interface to :cfunc:`PyImport_ImportModuleEx` below,
17 leaving the *globals* and *locals* arguments set to *NULL* and *level* set
19 argument contains a dot (when it specifies a submodule of a package), the
20 *fromlist* argument is set to the list ``['*']`` so that the return value is the
21 named module rather than the top-level package containing it as would otherwise
22 be the case. (Unfortunately, this has an additional side effect when *name* in
23 fact specifies a subpackage instead of a submodule: the submodules specified in
24 the package's ``__all__`` variable are loaded.) Return a new reference to the
25 imported module, or *NULL* with an exception set on failure. Before Python 2.4,
26 the module may still be created in the failure case --- examine ``sys.modules``
27 to find out. Starting with Python 2.4, a failing import of a module no longer
28 leaves the module in ``sys.modules``.
30 .. versionchanged:: 2.4
31 Failing imports remove incomplete module objects.
33 .. versionchanged:: 2.6
34 Always uses absolute imports.
37 .. cfunction:: PyObject* PyImport_ImportModuleNoBlock(const char *name)
39 This version of :cfunc:`PyImport_ImportModule` does not block. It's intended
40 to be used in C functions that import other modules to execute a function.
41 The import may block if another thread holds the import lock. The function
42 :cfunc:`PyImport_ImportModuleNoBlock` never blocks. It first tries to fetch
43 the module from sys.modules and falls back to :cfunc:`PyImport_ImportModule`
44 unless the lock is held, in which case the function will raise an
50 .. cfunction:: PyObject* PyImport_ImportModuleEx(char *name, PyObject *globals, PyObject *locals, PyObject *fromlist)
52 .. index:: builtin: __import__
54 Import a module. This is best described by referring to the built-in Python
55 function :func:`__import__`, as the standard :func:`__import__` function calls
56 this function directly.
58 The return value is a new reference to the imported module or top-level package,
59 or *NULL* with an exception set on failure (before Python 2.4, the module may
60 still be created in this case). Like for :func:`__import__`, the return value
61 when a submodule of a package was requested is normally the top-level package,
62 unless a non-empty *fromlist* was given.
64 .. versionchanged:: 2.4
65 Failing imports remove incomplete module objects.
67 .. versionchanged:: 2.6
68 The function is an alias for :cfunc:`PyImport_ImportModuleLevel` with
69 -1 as level, meaning relative import.
72 .. cfunction:: PyObject* PyImport_ImportModuleLevel(char *name, PyObject *globals, PyObject *locals, PyObject *fromlist, int level)
74 Import a module. This is best described by referring to the built-in Python
75 function :func:`__import__`, as the standard :func:`__import__` function calls
76 this function directly.
78 The return value is a new reference to the imported module or top-level package,
79 or *NULL* with an exception set on failure. Like for :func:`__import__`,
80 the return value when a submodule of a package was requested is normally the
81 top-level package, unless a non-empty *fromlist* was given.
86 .. cfunction:: PyObject* PyImport_Import(PyObject *name)
92 This is a higher-level interface that calls the current "import hook function".
93 It invokes the :func:`__import__` function from the ``__builtins__`` of the
94 current globals. This means that the import is done using whatever import hooks
95 are installed in the current environment, e.g. by :mod:`rexec` or :mod:`ihooks`.
97 .. versionchanged:: 2.6
98 Always uses absolute imports.
101 .. cfunction:: PyObject* PyImport_ReloadModule(PyObject *m)
103 .. index:: builtin: reload
105 Reload a module. This is best described by referring to the built-in Python
106 function :func:`reload`, as the standard :func:`reload` function calls this
107 function directly. Return a new reference to the reloaded module, or *NULL*
108 with an exception set on failure (the module still exists in this case).
111 .. cfunction:: PyObject* PyImport_AddModule(const char *name)
113 Return the module object corresponding to a module name. The *name* argument
114 may be of the form ``package.module``. First check the modules dictionary if
115 there's one there, and if not, create a new one and insert it in the modules
116 dictionary. Return *NULL* with an exception set on failure.
120 This function does not load or import the module; if the module wasn't already
121 loaded, you will get an empty module object. Use :cfunc:`PyImport_ImportModule`
122 or one of its variants to import a module. Package structures implied by a
123 dotted name for *name* are not created if not already present.
126 .. cfunction:: PyObject* PyImport_ExecCodeModule(char *name, PyObject *co)
128 .. index:: builtin: compile
130 Given a module name (possibly of the form ``package.module``) and a code object
131 read from a Python bytecode file or obtained from the built-in function
132 :func:`compile`, load the module. Return a new reference to the module object,
133 or *NULL* with an exception set if an error occurred. Before Python 2.4, the
134 module could still be created in error cases. Starting with Python 2.4, *name*
135 is removed from :attr:`sys.modules` in error cases, and even if *name* was already
136 in :attr:`sys.modules` on entry to :cfunc:`PyImport_ExecCodeModule`. Leaving
137 incompletely initialized modules in :attr:`sys.modules` is dangerous, as imports of
138 such modules have no way to know that the module object is an unknown (and
139 probably damaged with respect to the module author's intents) state.
141 This function will reload the module if it was already imported. See
142 :cfunc:`PyImport_ReloadModule` for the intended way to reload a module.
144 If *name* points to a dotted name of the form ``package.module``, any package
145 structures not already created will still not be created.
147 .. versionchanged:: 2.4
148 *name* is removed from :attr:`sys.modules` in error cases.
151 .. cfunction:: long PyImport_GetMagicNumber()
153 Return the magic number for Python bytecode files (a.k.a. :file:`.pyc` and
154 :file:`.pyo` files). The magic number should be present in the first four bytes
155 of the bytecode file, in little-endian byte order.
158 .. cfunction:: PyObject* PyImport_GetModuleDict()
160 Return the dictionary used for the module administration (a.k.a.
161 ``sys.modules``). Note that this is a per-interpreter variable.
164 .. cfunction:: PyObject* PyImport_GetImporter(PyObject *path)
166 Return an importer object for a :data:`sys.path`/:attr:`pkg.__path__` item
167 *path*, possibly by fetching it from the :data:`sys.path_importer_cache`
168 dict. If it wasn't yet cached, traverse :data:`sys.path_hooks` until a hook
169 is found that can handle the path item. Return ``None`` if no hook could;
170 this tells our caller it should fall back to the built-in import mechanism.
171 Cache the result in :data:`sys.path_importer_cache`. Return a new reference
172 to the importer object.
174 .. versionadded:: 2.6
177 .. cfunction:: void _PyImport_Init()
179 Initialize the import mechanism. For internal use only.
182 .. cfunction:: void PyImport_Cleanup()
184 Empty the module table. For internal use only.
187 .. cfunction:: void _PyImport_Fini()
189 Finalize the import mechanism. For internal use only.
192 .. cfunction:: PyObject* _PyImport_FindExtension(char *, char *)
194 For internal use only.
197 .. cfunction:: PyObject* _PyImport_FixupExtension(char *, char *)
199 For internal use only.
202 .. cfunction:: int PyImport_ImportFrozenModule(char *name)
204 Load a frozen module named *name*. Return ``1`` for success, ``0`` if the
205 module is not found, and ``-1`` with an exception set if the initialization
206 failed. To access the imported module on a successful load, use
207 :cfunc:`PyImport_ImportModule`. (Note the misnomer --- this function would
208 reload the module if it was already imported.)
211 .. ctype:: struct _frozen
213 .. index:: single: freeze utility
215 This is the structure type definition for frozen module descriptors, as
216 generated by the :program:`freeze` utility (see :file:`Tools/freeze/` in the
217 Python source distribution). Its definition, found in :file:`Include/import.h`,
227 .. cvar:: struct _frozen* PyImport_FrozenModules
229 This pointer is initialized to point to an array of :ctype:`struct _frozen`
230 records, terminated by one whose members are all *NULL* or zero. When a frozen
231 module is imported, it is searched in this table. Third-party code could play
232 tricks with this to provide a dynamically created collection of frozen modules.
235 .. cfunction:: int PyImport_AppendInittab(const char *name, void (*initfunc)(void))
237 Add a single module to the existing table of built-in modules. This is a
238 convenience wrapper around :cfunc:`PyImport_ExtendInittab`, returning ``-1`` if
239 the table could not be extended. The new module can be imported by the name
240 *name*, and uses the function *initfunc* as the initialization function called
241 on the first attempted import. This should be called before
242 :cfunc:`Py_Initialize`.
245 .. ctype:: struct _inittab
247 Structure describing a single entry in the list of built-in modules. Each of
248 these structures gives the name and initialization function for a module built
249 into the interpreter. Programs which embed Python may use an array of these
250 structures in conjunction with :cfunc:`PyImport_ExtendInittab` to provide
251 additional built-in modules. The structure is defined in
252 :file:`Include/import.h` as::
256 void (*initfunc)(void);
260 .. cfunction:: int PyImport_ExtendInittab(struct _inittab *newtab)
262 Add a collection of modules to the table of built-in modules. The *newtab*
263 array must end with a sentinel entry which contains *NULL* for the :attr:`name`
264 field; failure to provide the sentinel value can result in a memory fault.
265 Returns ``0`` on success or ``-1`` if insufficient memory could be allocated to
266 extend the internal table. In the event of failure, no modules are added to the
267 internal table. This should be called before :cfunc:`Py_Initialize`.