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. A failing 26 import of a module doesn't leave the module in :data:`sys.modules`. 27 28 This function always uses absolute imports. 29 30 31 .. c:function:: PyObject* PyImport_ImportModuleNoBlock(const char *name) 32 33 This function is a deprecated alias of :c:func:`PyImport_ImportModule`. 34 35 .. versionchanged:: 3.3 36 This function used to fail immediately when the import lock was held 37 by another thread. In Python 3.3 though, the locking scheme switched 38 to per-module locks for most purposes, so this function's special 39 behaviour isn't needed anymore. 40 41 42 .. c:function:: PyObject* PyImport_ImportModuleEx(const char *name, PyObject *globals, PyObject *locals, PyObject *fromlist) 43 44 .. index:: builtin: __import__ 45 46 Import a module. This is best described by referring to the built-in Python 47 function :func:`__import__`. 48 49 The return value is a new reference to the imported module or top-level 50 package, or *NULL* with an exception set on failure. Like for 51 :func:`__import__`, the return value when a submodule of a package was 52 requested is normally the top-level package, unless a non-empty *fromlist* 53 was given. 54 55 Failing imports remove incomplete module objects, like with 56 :c:func:`PyImport_ImportModule`. 57 58 59 .. c:function:: PyObject* PyImport_ImportModuleLevelObject(PyObject *name, PyObject *globals, PyObject *locals, PyObject *fromlist, int level) 60 61 Import a module. This is best described by referring to the built-in Python 62 function :func:`__import__`, as the standard :func:`__import__` function calls 63 this function directly. 64 65 The return value is a new reference to the imported module or top-level package, 66 or *NULL* with an exception set on failure. Like for :func:`__import__`, 67 the return value when a submodule of a package was requested is normally the 68 top-level package, unless a non-empty *fromlist* was given. 69 70 .. versionadded:: 3.3 71 72 73 .. c:function:: PyObject* PyImport_ImportModuleLevel(const char *name, PyObject *globals, PyObject *locals, PyObject *fromlist, int level) 74 75 Similar to :c:func:`PyImport_ImportModuleLevelObject`, but the name is a 76 UTF-8 encoded string instead of a Unicode object. 77 78 .. versionchanged:: 3.3 79 Negative values for *level* are no longer accepted. 80 81 .. c:function:: PyObject* PyImport_Import(PyObject *name) 82 83 This is a higher-level interface that calls the current "import hook 84 function" (with an explicit *level* of 0, meaning absolute import). It 85 invokes the :func:`__import__` function from the ``__builtins__`` of the 86 current globals. This means that the import is done using whatever import 87 hooks are installed in the current environment. 88 89 This function always uses absolute imports. 90 91 92 .. c:function:: PyObject* PyImport_ReloadModule(PyObject *m) 93 94 Reload a module. Return a new reference to the reloaded module, or *NULL* with 95 an exception set on failure (the module still exists in this case). 96 97 98 .. c:function:: PyObject* PyImport_AddModuleObject(PyObject *name) 99 100 Return the module object corresponding to a module name. The *name* argument 101 may be of the form ``package.module``. First check the modules dictionary if 102 there's one there, and if not, create a new one and insert it in the modules 103 dictionary. Return *NULL* with an exception set on failure. 104 105 .. note:: 106 107 This function does not load or import the module; if the module wasn't already 108 loaded, you will get an empty module object. Use :c:func:`PyImport_ImportModule` 109 or one of its variants to import a module. Package structures implied by a 110 dotted name for *name* are not created if not already present. 111 112 .. versionadded:: 3.3 113 114 115 .. c:function:: PyObject* PyImport_AddModule(const char *name) 116 117 Similar to :c:func:`PyImport_AddModuleObject`, but the name is a UTF-8 118 encoded string instead of a Unicode object. 119 120 121 .. c:function:: PyObject* PyImport_ExecCodeModule(const char *name, PyObject *co) 122 123 .. index:: builtin: compile 124 125 Given a module name (possibly of the form ``package.module``) and a code object 126 read from a Python bytecode file or obtained from the built-in function 127 :func:`compile`, load the module. Return a new reference to the module object, 128 or *NULL* with an exception set if an error occurred. *name* 129 is removed from :attr:`sys.modules` in error cases, even if *name* was already 130 in :attr:`sys.modules` on entry to :c:func:`PyImport_ExecCodeModule`. Leaving 131 incompletely initialized modules in :attr:`sys.modules` is dangerous, as imports of 132 such modules have no way to know that the module object is an unknown (and 133 probably damaged with respect to the module author's intents) state. 134 135 The module's :attr:`__spec__` and :attr:`__loader__` will be set, if 136 not set already, with the appropriate values. The spec's loader will 137 be set to the module's ``__loader__`` (if set) and to an instance of 138 :class:`SourceFileLoader` otherwise. 139 140 The module's :attr:`__file__` attribute will be set to the code object's 141 :c:member:`co_filename`. If applicable, :attr:`__cached__` will also 142 be set. 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 See also :c:func:`PyImport_ExecCodeModuleEx` and 151 :c:func:`PyImport_ExecCodeModuleWithPathnames`. 152 153 154 .. c:function:: PyObject* PyImport_ExecCodeModuleEx(const char *name, PyObject *co, const 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 See also :c:func:`PyImport_ExecCodeModuleWithPathnames`. 160 161 162 .. c:function:: PyObject* PyImport_ExecCodeModuleObject(PyObject *name, PyObject *co, PyObject *pathname, PyObject *cpathname) 163 164 Like :c:func:`PyImport_ExecCodeModuleEx`, but the :attr:`__cached__` 165 attribute of the module object is set to *cpathname* if it is 166 non-``NULL``. Of the three functions, this is the preferred one to use. 167 168 .. versionadded:: 3.3 169 170 171 .. c:function:: PyObject* PyImport_ExecCodeModuleWithPathnames(const char *name, PyObject *co, const char *pathname, const char *cpathname) 172 173 Like :c:func:`PyImport_ExecCodeModuleObject`, but *name*, *pathname* and 174 *cpathname* are UTF-8 encoded strings. Attempts are also made to figure out 175 what the value for *pathname* should be from *cpathname* if the former is 176 set to ``NULL``. 177 178 .. versionadded:: 3.2 179 .. versionchanged:: 3.3 180 Uses :func:`imp.source_from_cache()` in calculating the source path if 181 only the bytecode path is provided. 182 183 184 .. c:function:: long PyImport_GetMagicNumber() 185 186 Return the magic number for Python bytecode files (a.k.a. :file:`.pyc` file). 187 The magic number should be present in the first four bytes of the bytecode 188 file, in little-endian byte order. Returns ``-1`` on error. 189 190 .. versionchanged:: 3.3 191 Return value of ``-1`` upon failure. 192 193 194 .. c:function:: const char * PyImport_GetMagicTag() 195 196 Return the magic tag string for :pep:`3147` format Python bytecode file 197 names. Keep in mind that the value at ``sys.implementation.cache_tag`` is 198 authoritative and should be used instead of this function. 199 200 .. versionadded:: 3.2 201 202 .. c:function:: PyObject* PyImport_GetModuleDict() 203 204 Return the dictionary used for the module administration (a.k.a. 205 ``sys.modules``). Note that this is a per-interpreter variable. 206 207 208 .. c:function:: PyObject* PyImport_GetImporter(PyObject *path) 209 210 Return a finder object for a :data:`sys.path`/:attr:`pkg.__path__` item 211 *path*, possibly by fetching it from the :data:`sys.path_importer_cache` 212 dict. If it wasn't yet cached, traverse :data:`sys.path_hooks` until a hook 213 is found that can handle the path item. Return ``None`` if no hook could; 214 this tells our caller that the :term:`path based finder` could not find a 215 finder for this path item. Cache the result in :data:`sys.path_importer_cache`. 216 Return a new reference to the finder object. 217 218 219 .. c:function:: void _PyImport_Init() 220 221 Initialize the import mechanism. For internal use only. 222 223 224 .. c:function:: void PyImport_Cleanup() 225 226 Empty the module table. For internal use only. 227 228 229 .. c:function:: void _PyImport_Fini() 230 231 Finalize the import mechanism. For internal use only. 232 233 234 .. c:function:: PyObject* _PyImport_FindExtension(char *, char *) 235 236 For internal use only. 237 238 239 .. c:function:: int PyImport_ImportFrozenModuleObject(PyObject *name) 240 241 Load a frozen module named *name*. Return ``1`` for success, ``0`` if the 242 module is not found, and ``-1`` with an exception set if the initialization 243 failed. To access the imported module on a successful load, use 244 :c:func:`PyImport_ImportModule`. (Note the misnomer --- this function would 245 reload the module if it was already imported.) 246 247 .. versionadded:: 3.3 248 249 .. versionchanged:: 3.4 250 The ``__file__`` attribute is no longer set on the module. 251 252 253 .. c:function:: int PyImport_ImportFrozenModule(const char *name) 254 255 Similar to :c:func:`PyImport_ImportFrozenModuleObject`, but the name is a 256 UTF-8 encoded string instead of a Unicode object. 257 258 259 .. c:type:: struct _frozen 260 261 .. index:: single: freeze utility 262 263 This is the structure type definition for frozen module descriptors, as 264 generated by the :program:`freeze` utility (see :file:`Tools/freeze/` in the 265 Python source distribution). Its definition, found in :file:`Include/import.h`, 266 is:: 267 268 struct _frozen { 269 char *name; 270 unsigned char *code; 271 int size; 272 }; 273 274 275 .. c:var:: const struct _frozen* PyImport_FrozenModules 276 277 This pointer is initialized to point to an array of :c:type:`struct _frozen` 278 records, terminated by one whose members are all *NULL* or zero. When a frozen 279 module is imported, it is searched in this table. Third-party code could play 280 tricks with this to provide a dynamically created collection of frozen modules. 281 282 283 .. c:function:: int PyImport_AppendInittab(const char *name, PyObject* (*initfunc)(void)) 284 285 Add a single module to the existing table of built-in modules. This is a 286 convenience wrapper around :c:func:`PyImport_ExtendInittab`, returning ``-1`` if 287 the table could not be extended. The new module can be imported by the name 288 *name*, and uses the function *initfunc* as the initialization function called 289 on the first attempted import. This should be called before 290 :c:func:`Py_Initialize`. 291 292 293 .. c:type:: struct _inittab 294 295 Structure describing a single entry in the list of built-in modules. Each of 296 these structures gives the name and initialization function for a module built 297 into the interpreter. The name is an ASCII encoded string. Programs which 298 embed Python may use an array of these structures in conjunction with 299 :c:func:`PyImport_ExtendInittab` to provide additional built-in modules. 300 The structure is defined in :file:`Include/import.h` as:: 301 302 struct _inittab { 303 char *name; /* ASCII encoded string */ 304 PyObject* (*initfunc)(void); 305 }; 306 307 308 .. c:function:: int PyImport_ExtendInittab(struct _inittab *newtab) 309 310 Add a collection of modules to the table of built-in modules. The *newtab* 311 array must end with a sentinel entry which contains *NULL* for the :attr:`name` 312 field; failure to provide the sentinel value can result in a memory fault. 313 Returns ``0`` on success or ``-1`` if insufficient memory could be allocated to 314 extend the internal table. In the event of failure, no modules are added to the 315 internal table. This should be called before :c:func:`Py_Initialize`. 316
