Mercurial > cpython-lru_cache-weakref

annotate Doc/c-api/import.rst @ 54294:dba767bc3155 legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
remove mention of old ctypes version
author Benjamin Peterson <benjamin@python.org>
date Sat, 23 May 2009 20:59:09 +0000
parents 1ef3da6c434c
children acaa0c87d401
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
1 .. highlightlang:: c
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
2
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
3 .. _importing:
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
4
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
5 Importing Modules
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
6 =================
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
7
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
8
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
9 .. cfunction:: PyObject* PyImport_ImportModule(const char *name)
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
10
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
11 .. index::
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
12 single: package variable; __all__
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
13 single: __all__ (package variable)
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
14 single: modules (in module sys)
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
15
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
16 This is a simplified interface to :cfunc:`PyImport_ImportModuleEx` below,
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
17 leaving the *globals* and *locals* arguments set to *NULL* and *level* set
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
18 to 0. When the *name*
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
19 argument contains a dot (when it specifies a submodule of a package), the
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
20 *fromlist* argument is set to the list ``['*']`` so that the return value is the
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
21 named module rather than the top-level package containing it as would otherwise
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
22 be the case. (Unfortunately, this has an additional side effect when *name* in
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
23 fact specifies a subpackage instead of a submodule: the submodules specified in
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
24 the package's ``__all__`` variable are loaded.) Return a new reference to the
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
25 imported module, or *NULL* with an exception set on failure. Before Python 2.4,
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
26 the module may still be created in the failure case --- examine ``sys.modules``
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
27 to find out. Starting with Python 2.4, a failing import of a module no longer
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
28 leaves the module in ``sys.modules``.
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
29
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
30 .. versionchanged:: 2.4
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
31 failing imports remove incomplete module objects.
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
32
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
33 .. versionchanged:: 2.6
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
34 always use absolute imports
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
35
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
36
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
37 .. cfunction:: PyObject* PyImport_ImportModuleNoBlock(const char *name)
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
38
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
39 This version of :cfunc:`PyImport_ImportModule` does not block. It's intended
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
40 to be used in C functions that import other modules to execute a function.
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
41 The import may block if another thread holds the import lock. The function
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
42 :cfunc:`PyImport_ImportModuleNoBlock` never blocks. It first tries to fetch
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
43 the module from sys.modules and falls back to :cfunc:`PyImport_ImportModule`
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
44 unless the lock is held, in which case the function will raise an
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
45 :exc:`ImportError`.
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
46
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
47 .. versionadded:: 2.6
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
48
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
49
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
50 .. cfunction:: PyObject* PyImport_ImportModuleEx(char *name, PyObject *globals, PyObject *locals, PyObject *fromlist)
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
51
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
52 .. index:: builtin: __import__
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
53
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
54 Import a module. This is best described by referring to the built-in Python
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
55 function :func:`__import__`, as the standard :func:`__import__` function calls
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
56 this function directly.
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
57
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
58 The return value is a new reference to the imported module or top-level package,
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
59 or *NULL* with an exception set on failure (before Python 2.4, the module may
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
60 still be created in this case). Like for :func:`__import__`, the return value
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
61 when a submodule of a package was requested is normally the top-level package,
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
62 unless a non-empty *fromlist* was given.
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
63
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
64 .. versionchanged:: 2.4
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
65 failing imports remove incomplete module objects.
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
66
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
67 .. versionchanged:: 2.6
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
68 The function is an alias for :cfunc:`PyImport_ImportModuleLevel` with
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
69 -1 as level, meaning relative import.
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
70
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
71
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
72 .. cfunction:: PyObject* PyImport_ImportModuleLevel(char *name, PyObject *globals, PyObject *locals, PyObject *fromlist, int level)
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
73
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
74 Import a module. This is best described by referring to the built-in Python
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
75 function :func:`__import__`, as the standard :func:`__import__` function calls
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
76 this function directly.
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
77
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
78 The return value is a new reference to the imported module or top-level package,
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
79 or *NULL* with an exception set on failure. Like for :func:`__import__`,
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
80 the return value when a submodule of a package was requested is normally the
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
81 top-level package, unless a non-empty *fromlist* was given.
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
82
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
83 .. versionadded:: 2.5
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
84
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
85
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
86 .. cfunction:: PyObject* PyImport_Import(PyObject *name)
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
87
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
88 .. index::
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
89 module: rexec
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
90 module: ihooks
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
91
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
92 This is a higher-level interface that calls the current "import hook function".
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
93 It invokes the :func:`__import__` function from the ``__builtins__`` of the
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
94 current globals. This means that the import is done using whatever import hooks
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
95 are installed in the current environment, e.g. by :mod:`rexec` or :mod:`ihooks`.
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
96
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
97 .. versionchanged:: 2.6
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
98 always use absolute imports
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
99
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
100
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
101 .. cfunction:: PyObject* PyImport_ReloadModule(PyObject *m)
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
102
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
103 .. index:: builtin: reload
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
104
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
105 Reload a module. This is best described by referring to the built-in Python
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
106 function :func:`reload`, as the standard :func:`reload` function calls this
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
107 function directly. Return a new reference to the reloaded module, or *NULL*
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
108 with an exception set on failure (the module still exists in this case).
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
109
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
110
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
111 .. cfunction:: PyObject* PyImport_AddModule(const char *name)
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
112
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
113 Return the module object corresponding to a module name. The *name* argument
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
114 may be of the form ``package.module``. First check the modules dictionary if
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
115 there's one there, and if not, create a new one and insert it in the modules
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
116 dictionary. Return *NULL* with an exception set on failure.
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
117
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
118 .. note::
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
119
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
120 This function does not load or import the module; if the module wasn't already
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
121 loaded, you will get an empty module object. Use :cfunc:`PyImport_ImportModule`
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
122 or one of its variants to import a module. Package structures implied by a
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
123 dotted name for *name* are not created if not already present.
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
124
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
125
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
126 .. cfunction:: PyObject* PyImport_ExecCodeModule(char *name, PyObject *co)
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
127
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
128 .. index:: builtin: compile
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
129
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
130 Given a module name (possibly of the form ``package.module``) and a code object
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
131 read from a Python bytecode file or obtained from the built-in function
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
132 :func:`compile`, load the module. Return a new reference to the module object,
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
133 or *NULL* with an exception set if an error occurred. Before Python 2.4, the
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
134 module could still be created in error cases. Starting with Python 2.4, *name*
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
135 is removed from :attr:`sys.modules` in error cases, and even if *name* was already
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
136 in :attr:`sys.modules` on entry to :cfunc:`PyImport_ExecCodeModule`. Leaving
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
137 incompletely initialized modules in :attr:`sys.modules` is dangerous, as imports of
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
138 such modules have no way to know that the module object is an unknown (and
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
139 probably damaged with respect to the module author's intents) state.
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
140
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
141 This function will reload the module if it was already imported. See
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
142 :cfunc:`PyImport_ReloadModule` for the intended way to reload a module.
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
143
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
144 If *name* points to a dotted name of the form ``package.module``, any package
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
145 structures not already created will still not be created.
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
146
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
147 .. versionchanged:: 2.4
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
148 *name* is removed from :attr:`sys.modules` in error cases.
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
149
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
150
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
151 .. cfunction:: long PyImport_GetMagicNumber()
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
152
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
153 Return the magic number for Python bytecode files (a.k.a. :file:`.pyc` and
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
154 :file:`.pyo` files). The magic number should be present in the first four bytes
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
155 of the bytecode file, in little-endian byte order.
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
156
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
157
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
158 .. cfunction:: PyObject* PyImport_GetModuleDict()
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
159
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
160 Return the dictionary used for the module administration (a.k.a.
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
161 ``sys.modules``). Note that this is a per-interpreter variable.
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
162
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
163
45987
d6793ece3254 #2160: document PyImport_GetImporter.
Georg Brandl <georg@python.org>
parents: 44797
diff changeset
164 .. cfunction:: PyObject* PyImport_GetImporter(PyObject *path)
d6793ece3254 #2160: document PyImport_GetImporter.
Georg Brandl <georg@python.org>
parents: 44797
diff changeset
165
d6793ece3254 #2160: document PyImport_GetImporter.
Georg Brandl <georg@python.org>
parents: 44797
diff changeset
166 Return an importer object for a :data:`sys.path`/:attr:`pkg.__path__` item
d6793ece3254 #2160: document PyImport_GetImporter.
Georg Brandl <georg@python.org>
parents: 44797
diff changeset
167 *path*, possibly by fetching it from the :data:`sys.path_importer_cache`
d6793ece3254 #2160: document PyImport_GetImporter.
Georg Brandl <georg@python.org>
parents: 44797
diff changeset
168 dict. If it wasn't yet cached, traverse :data:`sys.path_hooks` until a hook
d6793ece3254 #2160: document PyImport_GetImporter.
Georg Brandl <georg@python.org>
parents: 44797
diff changeset
169 is found that can handle the path item. Return ``None`` if no hook could;
d6793ece3254 #2160: document PyImport_GetImporter.
Georg Brandl <georg@python.org>
parents: 44797
diff changeset
170 this tells our caller it should fall back to the builtin import mechanism.
d6793ece3254 #2160: document PyImport_GetImporter.
Georg Brandl <georg@python.org>
parents: 44797
diff changeset
171 Cache the result in :data:`sys.path_importer_cache`. Return a new reference
d6793ece3254 #2160: document PyImport_GetImporter.
Georg Brandl <georg@python.org>
parents: 44797
diff changeset
172 to the importer object.
d6793ece3254 #2160: document PyImport_GetImporter.
Georg Brandl <georg@python.org>
parents: 44797
diff changeset
173
d6793ece3254 #2160: document PyImport_GetImporter.
Georg Brandl <georg@python.org>
parents: 44797
diff changeset
174 .. versionadded:: 2.6
d6793ece3254 #2160: document PyImport_GetImporter.
Georg Brandl <georg@python.org>
parents: 44797
diff changeset
175
d6793ece3254 #2160: document PyImport_GetImporter.
Georg Brandl <georg@python.org>
parents: 44797
diff changeset
176
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
177 .. cfunction:: void _PyImport_Init()
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
178
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
179 Initialize the import mechanism. For internal use only.
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
180
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
181
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
182 .. cfunction:: void PyImport_Cleanup()
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
183
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
184 Empty the module table. For internal use only.
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
185
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
186
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
187 .. cfunction:: void _PyImport_Fini()
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
188
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
189 Finalize the import mechanism. For internal use only.
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
190
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
191
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
192 .. cfunction:: PyObject* _PyImport_FindExtension(char *, char *)
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
193
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
194 For internal use only.
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
195
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
196
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
197 .. cfunction:: PyObject* _PyImport_FixupExtension(char *, char *)
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
198
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
199 For internal use only.
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
200
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
201
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
202 .. cfunction:: int PyImport_ImportFrozenModule(char *name)
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
203
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
204 Load a frozen module named *name*. Return ``1`` for success, ``0`` if the
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
205 module is not found, and ``-1`` with an exception set if the initialization
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
206 failed. To access the imported module on a successful load, use
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
207 :cfunc:`PyImport_ImportModule`. (Note the misnomer --- this function would
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
208 reload the module if it was already imported.)
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
209
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
210
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
211 .. ctype:: struct _frozen
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
212
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
213 .. index:: single: freeze utility
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
214
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
215 This is the structure type definition for frozen module descriptors, as
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
216 generated by the :program:`freeze` utility (see :file:`Tools/freeze/` in the
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
217 Python source distribution). Its definition, found in :file:`Include/import.h`,
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
218 is::
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
219
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
220 struct _frozen {
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
221 char *name;
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
222 unsigned char *code;
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
223 int size;
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
224 };
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
225
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
226
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
227 .. cvar:: struct _frozen* PyImport_FrozenModules
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
228
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
229 This pointer is initialized to point to an array of :ctype:`struct _frozen`
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
230 records, terminated by one whose members are all *NULL* or zero. When a frozen
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
231 module is imported, it is searched in this table. Third-party code could play
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
232 tricks with this to provide a dynamically created collection of frozen modules.
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
233
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
234
52718
1ef3da6c434c PyImport_AppendInittab() took a char * as a first argument even though that
Brett Cannon <bcannon@gmail.com>
parents: 45987
diff changeset
235 .. cfunction:: int PyImport_AppendInittab(const char *name, void (*initfunc)(void))
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
236
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
237 Add a single module to the existing table of built-in modules. This is a
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
238 convenience wrapper around :cfunc:`PyImport_ExtendInittab`, returning ``-1`` if
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
239 the table could not be extended. The new module can be imported by the name
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
240 *name*, and uses the function *initfunc* as the initialization function called
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
241 on the first attempted import. This should be called before
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
242 :cfunc:`Py_Initialize`.
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
243
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
244
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
245 .. ctype:: struct _inittab
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
246
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
247 Structure describing a single entry in the list of built-in modules. Each of
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
248 these structures gives the name and initialization function for a module built
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
249 into the interpreter. Programs which embed Python may use an array of these
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
250 structures in conjunction with :cfunc:`PyImport_ExtendInittab` to provide
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
251 additional built-in modules. The structure is defined in
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
252 :file:`Include/import.h` as::
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
253
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
254 struct _inittab {
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
255 char *name;
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
256 void (*initfunc)(void);
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
257 };
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
258
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
259
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
260 .. cfunction:: int PyImport_ExtendInittab(struct _inittab *newtab)
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
261
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
262 Add a collection of modules to the table of built-in modules. The *newtab*
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
263 array must end with a sentinel entry which contains *NULL* for the :attr:`name`
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
264 field; failure to provide the sentinel value can result in a memory fault.
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
265 Returns ``0`` on success or ``-1`` if insufficient memory could be allocated to
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
266 extend the internal table. In the event of failure, no modules are added to the
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
267 internal table. This should be called before :cfunc:`Py_Initialize`.