|
1 .. highlightlang:: c |
|
2 |
|
3 .. _importing: |
|
4 |
|
5 Importing Modules |
|
6 ================= |
|
7 |
|
8 |
|
9 .. cfunction:: 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 :cfunc:`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 use absolute imports |
|
35 |
|
36 |
|
37 .. cfunction:: PyObject* PyImport_ImportModuleNoBlock(const char *name) |
|
38 |
|
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 |
|
45 :exc:`ImportError`. |
|
46 |
|
47 .. versionadded:: 2.6 |
|
48 |
|
49 |
|
50 .. cfunction:: 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 :cfunc:`PyImport_ImportModuleLevel` with |
|
69 -1 as level, meaning relative import. |
|
70 |
|
71 |
|
72 .. cfunction:: 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 .. cfunction:: 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 use absolute imports |
|
99 |
|
100 |
|
101 .. cfunction:: 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 .. cfunction:: 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 :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. |
|
124 |
|
125 |
|
126 .. cfunction:: 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 :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. |
|
140 |
|
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. |
|
143 |
|
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. |
|
146 |
|
147 .. versionchanged:: 2.4 |
|
148 *name* is removed from :attr:`sys.modules` in error cases. |
|
149 |
|
150 |
|
151 .. cfunction:: long PyImport_GetMagicNumber() |
|
152 |
|
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. |
|
156 |
|
157 |
|
158 .. cfunction:: PyObject* PyImport_GetModuleDict() |
|
159 |
|
160 Return the dictionary used for the module administration (a.k.a. |
|
161 ``sys.modules``). Note that this is a per-interpreter variable. |
|
162 |
|
163 |
|
164 .. cfunction:: PyObject* PyImport_GetImporter(PyObject *path) |
|
165 |
|
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 builtin import mechanism. |
|
171 Cache the result in :data:`sys.path_importer_cache`. Return a new reference |
|
172 to the importer object. |
|
173 |
|
174 .. versionadded:: 2.6 |
|
175 |
|
176 |
|
177 .. cfunction:: void _PyImport_Init() |
|
178 |
|
179 Initialize the import mechanism. For internal use only. |
|
180 |
|
181 |
|
182 .. cfunction:: void PyImport_Cleanup() |
|
183 |
|
184 Empty the module table. For internal use only. |
|
185 |
|
186 |
|
187 .. cfunction:: void _PyImport_Fini() |
|
188 |
|
189 Finalize the import mechanism. For internal use only. |
|
190 |
|
191 |
|
192 .. cfunction:: PyObject* _PyImport_FindExtension(char *, char *) |
|
193 |
|
194 For internal use only. |
|
195 |
|
196 |
|
197 .. cfunction:: PyObject* _PyImport_FixupExtension(char *, char *) |
|
198 |
|
199 For internal use only. |
|
200 |
|
201 |
|
202 .. cfunction:: int PyImport_ImportFrozenModule(char *name) |
|
203 |
|
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.) |
|
209 |
|
210 |
|
211 .. ctype:: struct _frozen |
|
212 |
|
213 .. index:: single: freeze utility |
|
214 |
|
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`, |
|
218 is:: |
|
219 |
|
220 struct _frozen { |
|
221 char *name; |
|
222 unsigned char *code; |
|
223 int size; |
|
224 }; |
|
225 |
|
226 |
|
227 .. cvar:: struct _frozen* PyImport_FrozenModules |
|
228 |
|
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. |
|
233 |
|
234 |
|
235 .. cfunction:: int PyImport_AppendInittab(char *name, void (*initfunc)(void)) |
|
236 |
|
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`. |
|
243 |
|
244 |
|
245 .. ctype:: struct _inittab |
|
246 |
|
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:: |
|
253 |
|
254 struct _inittab { |
|
255 char *name; |
|
256 void (*initfunc)(void); |
|
257 }; |
|
258 |
|
259 |
|
260 .. cfunction:: int PyImport_ExtendInittab(struct _inittab *newtab) |
|
261 |
|
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`. |