1 .. highlightlang:: c 2 3 .. _importing: 4 5 Importing Modules 6 ================= 7 8 9 .. c:function:: PyObject* PyImport_ImportModule(const char *name) 10 11 .. index:: 12 single: package variable; __all__ 13 single: __all__ (package variable) 14 single: modules (in module sys) 15 16 This is a simplified interface to :c:func:`PyImport_ImportModuleEx` below, 17 leaving the *globals* and *locals* arguments set to *NULL* and *level* set 18 to 0. When the *name* 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``. 29 30 .. versionchanged:: 2.4 31 Failing imports remove incomplete module objects. 32 33 .. versionchanged:: 2.6 34 Always uses absolute imports. 35 36 37 .. c:function:: PyObject* PyImport_ImportModuleNoBlock(const char *name) 38 39 This version of :c:func:`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 :c:func:`PyImport_ImportModuleNoBlock` never blocks. It first tries to fetch 43 the module from sys.modules and falls back to :c:func:`PyImport_ImportModule` 44 unless the lock is held, in which case the function will raise an 45 :exc:`ImportError`. 46 47 .. versionadded:: 2.6 48 49 50 .. c:function:: PyObject* PyImport_ImportModuleEx(char *name, PyObject *globals, PyObject *locals, PyObject *fromlist) 51 52 .. index:: builtin: __import__ 53 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. 57 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. 63 64 .. versionchanged:: 2.4 65 Failing imports remove incomplete module objects. 66 67 .. versionchanged:: 2.6 68 The function is an alias for :c:func:`PyImport_ImportModuleLevel` with 69 ``-1`` as level, meaning relative import. 70 71 72 .. c:function:: PyObject* PyImport_ImportModuleLevel(char *name, PyObject *globals, PyObject *locals, PyObject *fromlist, int level) 73 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. 77 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. 82 83 .. versionadded:: 2.5 84 85 86 .. c:function:: PyObject* PyImport_Import(PyObject *name) 87 88 .. index:: 89 module: rexec 90 module: ihooks 91 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`. 96 97 .. versionchanged:: 2.6 98 Always uses absolute imports. 99 100 101 .. c:function:: PyObject* PyImport_ReloadModule(PyObject *m) 102 103 .. index:: builtin: reload 104 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). 109 110 111 .. c:function:: PyObject* PyImport_AddModule(const char *name) 112 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. 117 118 .. note:: 119 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 :c:func:`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. 124 125 126 .. c:function:: PyObject* PyImport_ExecCodeModule(char *name, PyObject *co) 127 128 .. index:: builtin: compile 129 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 :c:func:`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. 140 141 The module's :attr:`__file__` attribute will be set to the code object's 142 :c:member:`co_filename`. 143 144 This function will reload the module if it was already imported. See 145 :c:func:`PyImport_ReloadModule` for the intended way to reload a module. 146 147 If *name* points to a dotted name of the form ``package.module``, any package 148 structures not already created will still not be created. 149 150 .. versionchanged:: 2.4 151 *name* is removed from :attr:`sys.modules` in error cases. 152 153 154 .. c:function:: PyObject* PyImport_ExecCodeModuleEx(char *name, PyObject *co, char *pathname) 155 156 Like :c:func:`PyImport_ExecCodeModule`, but the :attr:`__file__` attribute of 157 the module object is set to *pathname* if it is non-``NULL``. 158 159 160 .. c:function:: long PyImport_GetMagicNumber() 161 162 Return the magic number for Python bytecode files (a.k.a. :file:`.pyc` and 163 :file:`.pyo` files). The magic number should be present in the first four bytes 164 of the bytecode file, in little-endian byte order. 165 166 167 .. c:function:: PyObject* PyImport_GetModuleDict() 168 169 Return the dictionary used for the module administration (a.k.a. 170 ``sys.modules``). Note that this is a per-interpreter variable. 171 172 173 .. c:function:: PyObject* PyImport_GetImporter(PyObject *path) 174 175 Return an importer object for a :data:`sys.path`/:attr:`pkg.__path__` item 176 *path*, possibly by fetching it from the :data:`sys.path_importer_cache` 177 dict. If it wasn't yet cached, traverse :data:`sys.path_hooks` until a hook 178 is found that can handle the path item. Return ``None`` if no hook could; 179 this tells our caller it should fall back to the built-in import mechanism. 180 Cache the result in :data:`sys.path_importer_cache`. Return a new reference 181 to the importer object. 182 183 .. versionadded:: 2.6 184 185 186 .. c:function:: void _PyImport_Init() 187 188 Initialize the import mechanism. For internal use only. 189 190 191 .. c:function:: void PyImport_Cleanup() 192 193 Empty the module table. For internal use only. 194 195 196 .. c:function:: void _PyImport_Fini() 197 198 Finalize the import mechanism. For internal use only. 199 200 201 .. c:function:: PyObject* _PyImport_FindExtension(char *, char *) 202 203 For internal use only. 204 205 206 .. c:function:: PyObject* _PyImport_FixupExtension(char *, char *) 207 208 For internal use only. 209 210 211 .. c:function:: int PyImport_ImportFrozenModule(char *name) 212 213 Load a frozen module named *name*. Return ``1`` for success, ``0`` if the 214 module is not found, and ``-1`` with an exception set if the initialization 215 failed. To access the imported module on a successful load, use 216 :c:func:`PyImport_ImportModule`. (Note the misnomer --- this function would 217 reload the module if it was already imported.) 218 219 220 .. c:type:: struct _frozen 221 222 .. index:: single: freeze utility 223 224 This is the structure type definition for frozen module descriptors, as 225 generated by the :program:`freeze` utility (see :file:`Tools/freeze/` in the 226 Python source distribution). Its definition, found in :file:`Include/import.h`, 227 is:: 228 229 struct _frozen { 230 char *name; 231 unsigned char *code; 232 int size; 233 }; 234 235 236 .. c:var:: struct _frozen* PyImport_FrozenModules 237 238 This pointer is initialized to point to an array of :c:type:`struct _frozen` 239 records, terminated by one whose members are all *NULL* or zero. When a frozen 240 module is imported, it is searched in this table. Third-party code could play 241 tricks with this to provide a dynamically created collection of frozen modules. 242 243 244 .. c:function:: int PyImport_AppendInittab(const char *name, void (*initfunc)(void)) 245 246 Add a single module to the existing table of built-in modules. This is a 247 convenience wrapper around :c:func:`PyImport_ExtendInittab`, returning ``-1`` if 248 the table could not be extended. The new module can be imported by the name 249 *name*, and uses the function *initfunc* as the initialization function called 250 on the first attempted import. This should be called before 251 :c:func:`Py_Initialize`. 252 253 254 .. c:type:: struct _inittab 255 256 Structure describing a single entry in the list of built-in modules. Each of 257 these structures gives the name and initialization function for a module built 258 into the interpreter. Programs which embed Python may use an array of these 259 structures in conjunction with :c:func:`PyImport_ExtendInittab` to provide 260 additional built-in modules. The structure is defined in 261 :file:`Include/import.h` as:: 262 263 struct _inittab { 264 char *name; 265 void (*initfunc)(void); 266 }; 267 268 269 .. c:function:: int PyImport_ExtendInittab(struct _inittab *newtab) 270 271 Add a collection of modules to the table of built-in modules. The *newtab* 272 array must end with a sentinel entry which contains *NULL* for the :attr:`name` 273 field; failure to provide the sentinel value can result in a memory fault. 274 Returns ``0`` on success or ``-1`` if insufficient memory could be allocated to 275 extend the internal table. In the event of failure, no modules are added to the 276 internal table. This should be called before :c:func:`Py_Initialize`. 277
