/Doc/c-api/import.rst

  1.. highlightlang:: c
  2
  3.. _importing:
  4
  5Importing 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`.