Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1 | .. highlightlang:: c |
| 2 | |
| 3 | .. _importing: |
| 4 | |
| 5 | Importing Modules |
| 6 | ================= |
| 7 | |
| 8 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 9 | .. c:function:: PyObject* PyImport_ImportModule(const char *name) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 10 | |
| 11 | .. index:: |
| 12 | single: package variable; __all__ |
| 13 | single: __all__ (package variable) |
| 14 | single: modules (in module sys) |
| 15 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 16 | This is a simplified interface to :c:func:`PyImport_ImportModuleEx` below, |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 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 |
Georg Brandl | e6bcc91 | 2008-05-12 18:05:20 +0000 | [diff] [blame] | 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`. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 27 | |
Alexandre Vassalotti | 711ed4a | 2009-07-17 10:42:05 +0000 | [diff] [blame] | 28 | This function always uses absolute imports. |
| 29 | |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 30 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 31 | .. c:function:: PyObject* PyImport_ImportModuleNoBlock(const char *name) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 32 | |
Antoine Pitrou | ea3eb88 | 2012-05-17 18:55:59 +0200 | [diff] [blame] | 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. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 40 | |
| 41 | |
Serhiy Storchaka | 03863d2 | 2015-06-21 17:11:21 +0300 | [diff] [blame] | 42 | .. c:function:: PyObject* PyImport_ImportModuleEx(const char *name, PyObject *globals, PyObject *locals, PyObject *fromlist) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 43 | |
| 44 | .. index:: builtin: __import__ |
| 45 | |
| 46 | Import a module. This is best described by referring to the built-in Python |
Brett Cannon | 522267e | 2012-08-10 18:55:08 -0400 | [diff] [blame] | 47 | function :func:`__import__`. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 48 | |
Georg Brandl | e6bcc91 | 2008-05-12 18:05:20 +0000 | [diff] [blame] | 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. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 54 | |
| 55 | Failing imports remove incomplete module objects, like with |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 56 | :c:func:`PyImport_ImportModule`. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 57 | |
| 58 | |
Victor Stinner | fe93faf | 2011-03-14 15:54:52 -0400 | [diff] [blame] | 59 | .. c:function:: PyObject* PyImport_ImportModuleLevelObject(PyObject *name, PyObject *globals, PyObject *locals, PyObject *fromlist, int level) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 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 | |
Victor Stinner | fe93faf | 2011-03-14 15:54:52 -0400 | [diff] [blame] | 70 | .. versionadded:: 3.3 |
| 71 | |
| 72 | |
Serhiy Storchaka | 03863d2 | 2015-06-21 17:11:21 +0300 | [diff] [blame] | 73 | .. c:function:: PyObject* PyImport_ImportModuleLevel(const char *name, PyObject *globals, PyObject *locals, PyObject *fromlist, int level) |
Victor Stinner | fe93faf | 2011-03-14 15:54:52 -0400 | [diff] [blame] | 74 | |
| 75 | Similar to :c:func:`PyImport_ImportModuleLevelObject`, but the name is an |
| 76 | UTF-8 encoded string instead of a Unicode object. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 77 | |
Brett Cannon | 522267e | 2012-08-10 18:55:08 -0400 | [diff] [blame] | 78 | .. versionchanged:: 3.3 |
Ezio Melotti | 7598e18 | 2012-09-20 08:33:53 +0300 | [diff] [blame] | 79 | Negative values for *level* are no longer accepted. |
Brett Cannon | 522267e | 2012-08-10 18:55:08 -0400 | [diff] [blame] | 80 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 81 | .. c:function:: PyObject* PyImport_Import(PyObject *name) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 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 | |
Alexandre Vassalotti | 711ed4a | 2009-07-17 10:42:05 +0000 | [diff] [blame] | 89 | This function always uses absolute imports. |
| 90 | |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 91 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 92 | .. c:function:: PyObject* PyImport_ReloadModule(PyObject *m) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 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 | |
Victor Stinner | 27ee089 | 2011-03-04 12:57:09 +0000 | [diff] [blame] | 98 | .. c:function:: PyObject* PyImport_AddModuleObject(PyObject *name) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 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 |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 108 | loaded, you will get an empty module object. Use :c:func:`PyImport_ImportModule` |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 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 | |
Victor Stinner | 27ee089 | 2011-03-04 12:57:09 +0000 | [diff] [blame] | 112 | .. versionadded:: 3.3 |
| 113 | |
| 114 | |
| 115 | .. c:function:: PyObject* PyImport_AddModule(const char *name) |
| 116 | |
Éric Araujo | 16e6f4c | 2011-03-20 18:08:19 +0100 | [diff] [blame] | 117 | Similar to :c:func:`PyImport_AddModuleObject`, but the name is a UTF-8 |
Victor Stinner | 27ee089 | 2011-03-04 12:57:09 +0000 | [diff] [blame] | 118 | encoded string instead of a Unicode object. |
| 119 | |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 120 | |
Serhiy Storchaka | c679227 | 2013-10-19 21:03:34 +0300 | [diff] [blame] | 121 | .. c:function:: PyObject* PyImport_ExecCodeModule(const char *name, PyObject *co) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 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, |
Georg Brandl | e6bcc91 | 2008-05-12 18:05:20 +0000 | [diff] [blame] | 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 |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 130 | in :attr:`sys.modules` on entry to :c:func:`PyImport_ExecCodeModule`. Leaving |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 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 | |
Eric Snow | 08197a4 | 2014-05-12 17:54:55 -0600 | [diff] [blame] | 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 | |
Benjamin Peterson | 08bf91c | 2010-04-11 16:12:57 +0000 | [diff] [blame] | 140 | The module's :attr:`__file__` attribute will be set to the code object's |
Eric Snow | 08197a4 | 2014-05-12 17:54:55 -0600 | [diff] [blame] | 141 | :c:member:`co_filename`. If applicable, :attr:`__cached__` will also |
| 142 | be set. |
Benjamin Peterson | 08bf91c | 2010-04-11 16:12:57 +0000 | [diff] [blame] | 143 | |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 144 | This function will reload the module if it was already imported. See |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 145 | :c:func:`PyImport_ReloadModule` for the intended way to reload a module. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 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 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 150 | See also :c:func:`PyImport_ExecCodeModuleEx` and |
| 151 | :c:func:`PyImport_ExecCodeModuleWithPathnames`. |
Barry Warsaw | 28a691b | 2010-04-17 00:19:56 +0000 | [diff] [blame] | 152 | |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 153 | |
Serhiy Storchaka | c679227 | 2013-10-19 21:03:34 +0300 | [diff] [blame] | 154 | .. c:function:: PyObject* PyImport_ExecCodeModuleEx(const char *name, PyObject *co, const char *pathname) |
Benjamin Peterson | 08bf91c | 2010-04-11 16:12:57 +0000 | [diff] [blame] | 155 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 156 | Like :c:func:`PyImport_ExecCodeModule`, but the :attr:`__file__` attribute of |
Benjamin Peterson | 08bf91c | 2010-04-11 16:12:57 +0000 | [diff] [blame] | 157 | the module object is set to *pathname* if it is non-``NULL``. |
| 158 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 159 | See also :c:func:`PyImport_ExecCodeModuleWithPathnames`. |
Barry Warsaw | 28a691b | 2010-04-17 00:19:56 +0000 | [diff] [blame] | 160 | |
| 161 | |
Victor Stinner | 27ee089 | 2011-03-04 12:57:09 +0000 | [diff] [blame] | 162 | .. c:function:: PyObject* PyImport_ExecCodeModuleObject(PyObject *name, PyObject *co, PyObject *pathname, PyObject *cpathname) |
Barry Warsaw | 28a691b | 2010-04-17 00:19:56 +0000 | [diff] [blame] | 163 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 164 | Like :c:func:`PyImport_ExecCodeModuleEx`, but the :attr:`__cached__` |
Barry Warsaw | 28a691b | 2010-04-17 00:19:56 +0000 | [diff] [blame] | 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 | |
Victor Stinner | 27ee089 | 2011-03-04 12:57:09 +0000 | [diff] [blame] | 168 | .. versionadded:: 3.3 |
| 169 | |
| 170 | |
Serhiy Storchaka | c679227 | 2013-10-19 21:03:34 +0300 | [diff] [blame] | 171 | .. c:function:: PyObject* PyImport_ExecCodeModuleWithPathnames(const char *name, PyObject *co, const char *pathname, const char *cpathname) |
Victor Stinner | 27ee089 | 2011-03-04 12:57:09 +0000 | [diff] [blame] | 172 | |
| 173 | Like :c:func:`PyImport_ExecCodeModuleObject`, but *name*, *pathname* and |
Brett Cannon | a6473f9 | 2012-07-13 13:57:03 -0400 | [diff] [blame] | 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``. |
Victor Stinner | 27ee089 | 2011-03-04 12:57:09 +0000 | [diff] [blame] | 177 | |
Éric Araujo | 930df31 | 2010-12-16 06:28:48 +0000 | [diff] [blame] | 178 | .. versionadded:: 3.2 |
Brett Cannon | a6473f9 | 2012-07-13 13:57:03 -0400 | [diff] [blame] | 179 | .. versionchanged:: 3.3 |
| 180 | Uses :func:`imp.source_from_cache()` in calculating the source path if |
| 181 | only the bytecode path is provided. |
Benjamin Peterson | 08bf91c | 2010-04-11 16:12:57 +0000 | [diff] [blame] | 182 | |
Victor Stinner | 27ee089 | 2011-03-04 12:57:09 +0000 | [diff] [blame] | 183 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 184 | .. c:function:: long PyImport_GetMagicNumber() |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 185 | |
Brett Cannon | f299abd | 2015-04-13 14:21:02 -0400 | [diff] [blame] | 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. |
Brett Cannon | 77b2abd | 2012-07-09 16:09:00 -0400 | [diff] [blame] | 189 | |
| 190 | .. versionchanged:: 3.3 |
| 191 | Return value of -1 upon failure. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 192 | |
| 193 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 194 | .. c:function:: const char * PyImport_GetMagicTag() |
Barry Warsaw | 28a691b | 2010-04-17 00:19:56 +0000 | [diff] [blame] | 195 | |
| 196 | Return the magic tag string for :pep:`3147` format Python bytecode file |
Brett Cannon | 3adc7b7 | 2012-07-09 14:22:12 -0400 | [diff] [blame] | 197 | names. Keep in mind that the value at ``sys.implementation.cache_tag`` is |
| 198 | authoritative and should be used instead of this function. |
Barry Warsaw | 28a691b | 2010-04-17 00:19:56 +0000 | [diff] [blame] | 199 | |
Éric Araujo | 930df31 | 2010-12-16 06:28:48 +0000 | [diff] [blame] | 200 | .. versionadded:: 3.2 |
| 201 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 202 | .. c:function:: PyObject* PyImport_GetModuleDict() |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 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 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 208 | .. c:function:: PyObject* PyImport_GetImporter(PyObject *path) |
Christian Heimes | 4fbc72b | 2008-03-22 00:47:35 +0000 | [diff] [blame] | 209 | |
| 210 | Return an importer 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; |
Georg Brandl | 22b3431 | 2009-07-26 14:54:51 +0000 | [diff] [blame] | 214 | this tells our caller it should fall back to the built-in import mechanism. |
Christian Heimes | 4fbc72b | 2008-03-22 00:47:35 +0000 | [diff] [blame] | 215 | Cache the result in :data:`sys.path_importer_cache`. Return a new reference |
| 216 | to the importer object. |
| 217 | |
Christian Heimes | 4fbc72b | 2008-03-22 00:47:35 +0000 | [diff] [blame] | 218 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 219 | .. c:function:: void _PyImport_Init() |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 220 | |
| 221 | Initialize the import mechanism. For internal use only. |
| 222 | |
| 223 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 224 | .. c:function:: void PyImport_Cleanup() |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 225 | |
| 226 | Empty the module table. For internal use only. |
| 227 | |
| 228 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 229 | .. c:function:: void _PyImport_Fini() |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 230 | |
| 231 | Finalize the import mechanism. For internal use only. |
| 232 | |
| 233 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 234 | .. c:function:: PyObject* _PyImport_FindExtension(char *, char *) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 235 | |
| 236 | For internal use only. |
| 237 | |
| 238 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 239 | .. c:function:: PyObject* _PyImport_FixupExtension(char *, char *) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 240 | |
| 241 | For internal use only. |
| 242 | |
| 243 | |
Victor Stinner | 53dc735 | 2011-03-20 01:50:21 +0100 | [diff] [blame] | 244 | .. c:function:: int PyImport_ImportFrozenModuleObject(PyObject *name) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 245 | |
| 246 | Load a frozen module named *name*. Return ``1`` for success, ``0`` if the |
| 247 | module is not found, and ``-1`` with an exception set if the initialization |
| 248 | failed. To access the imported module on a successful load, use |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 249 | :c:func:`PyImport_ImportModule`. (Note the misnomer --- this function would |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 250 | reload the module if it was already imported.) |
| 251 | |
Victor Stinner | 53dc735 | 2011-03-20 01:50:21 +0100 | [diff] [blame] | 252 | .. versionadded:: 3.3 |
| 253 | |
Brett Cannon | 18fc4e7 | 2014-04-04 10:01:46 -0400 | [diff] [blame] | 254 | .. versionchanged:: 3.4 |
| 255 | The ``__file__`` attribute is no longer set on the module. |
| 256 | |
Victor Stinner | 53dc735 | 2011-03-20 01:50:21 +0100 | [diff] [blame] | 257 | |
Serhiy Storchaka | c679227 | 2013-10-19 21:03:34 +0300 | [diff] [blame] | 258 | .. c:function:: int PyImport_ImportFrozenModule(const char *name) |
Victor Stinner | 53dc735 | 2011-03-20 01:50:21 +0100 | [diff] [blame] | 259 | |
Éric Araujo | 16e6f4c | 2011-03-20 18:08:19 +0100 | [diff] [blame] | 260 | Similar to :c:func:`PyImport_ImportFrozenModuleObject`, but the name is a |
Victor Stinner | 53dc735 | 2011-03-20 01:50:21 +0100 | [diff] [blame] | 261 | UTF-8 encoded string instead of a Unicode object. |
| 262 | |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 263 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 264 | .. c:type:: struct _frozen |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 265 | |
| 266 | .. index:: single: freeze utility |
| 267 | |
| 268 | This is the structure type definition for frozen module descriptors, as |
| 269 | generated by the :program:`freeze` utility (see :file:`Tools/freeze/` in the |
| 270 | Python source distribution). Its definition, found in :file:`Include/import.h`, |
| 271 | is:: |
| 272 | |
| 273 | struct _frozen { |
| 274 | char *name; |
| 275 | unsigned char *code; |
| 276 | int size; |
| 277 | }; |
| 278 | |
| 279 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 280 | .. c:var:: struct _frozen* PyImport_FrozenModules |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 281 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 282 | This pointer is initialized to point to an array of :c:type:`struct _frozen` |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 283 | records, terminated by one whose members are all *NULL* or zero. When a frozen |
| 284 | module is imported, it is searched in this table. Third-party code could play |
| 285 | tricks with this to provide a dynamically created collection of frozen modules. |
| 286 | |
| 287 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 288 | .. c:function:: int PyImport_AppendInittab(const char *name, PyObject* (*initfunc)(void)) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 289 | |
| 290 | Add a single module to the existing table of built-in modules. This is a |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 291 | convenience wrapper around :c:func:`PyImport_ExtendInittab`, returning ``-1`` if |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 292 | the table could not be extended. The new module can be imported by the name |
| 293 | *name*, and uses the function *initfunc* as the initialization function called |
| 294 | on the first attempted import. This should be called before |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 295 | :c:func:`Py_Initialize`. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 296 | |
| 297 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 298 | .. c:type:: struct _inittab |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 299 | |
| 300 | Structure describing a single entry in the list of built-in modules. Each of |
| 301 | these structures gives the name and initialization function for a module built |
Victor Stinner | db536af | 2011-03-07 18:34:59 +0100 | [diff] [blame] | 302 | into the interpreter. The name is an ASCII encoded string. Programs which |
| 303 | embed Python may use an array of these structures in conjunction with |
| 304 | :c:func:`PyImport_ExtendInittab` to provide additional built-in modules. |
| 305 | The structure is defined in :file:`Include/import.h` as:: |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 306 | |
| 307 | struct _inittab { |
Victor Stinner | db536af | 2011-03-07 18:34:59 +0100 | [diff] [blame] | 308 | char *name; /* ASCII encoded string */ |
Martin v. Löwis | 1a21451 | 2008-06-11 05:26:20 +0000 | [diff] [blame] | 309 | PyObject* (*initfunc)(void); |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 310 | }; |
| 311 | |
| 312 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 313 | .. c:function:: int PyImport_ExtendInittab(struct _inittab *newtab) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 314 | |
| 315 | Add a collection of modules to the table of built-in modules. The *newtab* |
| 316 | array must end with a sentinel entry which contains *NULL* for the :attr:`name` |
| 317 | field; failure to provide the sentinel value can result in a memory fault. |
| 318 | Returns ``0`` on success or ``-1`` if insufficient memory could be allocated to |
| 319 | extend the internal table. In the event of failure, no modules are added to the |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 320 | internal table. This should be called before :c:func:`Py_Initialize`. |