Mercurial > cpython-lru_cache-weakref

annotate Doc/c-api/import.rst @ 79675:c0a2294de787 2.7

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Issue #16199: Backport 2to3 typo fix from 3.2.
author Chris Jerdonek <chris.jerdonek@gmail.com>
date Thu, 11 Oct 2012 16:15:46 -0700
parents 9f664e163c9d
children
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
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
9 .. c:function:: PyObject* PyImport_ImportModule(const char *name)
44797
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
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
16 This is a simplified interface to :c:func:`PyImport_ImportModuleEx` below,
44797
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
56814
127d623396ab Merged revisions 73286,73294,73296,73459,73462-73463,73544,73576-73577,73595-73596,73693-73694,73704-73705,73707,73713,73937-73940,73945,73951,73979 via svnmerge from
Georg Brandl <georg@python.org>
parents: 45987
diff changeset
31 Failing imports remove incomplete module objects.
44797
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
56814
127d623396ab Merged revisions 73286,73294,73296,73459,73462-73463,73544,73576-73577,73595-73596,73693-73694,73704-73705,73707,73713,73937-73940,73945,73951,73979 via svnmerge from
Georg Brandl <georg@python.org>
parents: 45987
diff changeset
34 Always uses absolute imports.
44797
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
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
37 .. c:function:: PyObject* PyImport_ImportModuleNoBlock(const char *name)
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
38
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
39 This version of :c:func:`PyImport_ImportModule` does not block. It's intended
44797
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
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
42 :c:func:`PyImport_ImportModuleNoBlock` never blocks. It first tries to fetch
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
43 the module from sys.modules and falls back to :c:func:`PyImport_ImportModule`
44797
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
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
50 .. c:function:: PyObject* PyImport_ImportModuleEx(char *name, PyObject *globals, PyObject *locals, PyObject *fromlist)
44797
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
56814
127d623396ab Merged revisions 73286,73294,73296,73459,73462-73463,73544,73576-73577,73595-73596,73693-73694,73704-73705,73707,73713,73937-73940,73945,73951,73979 via svnmerge from
Georg Brandl <georg@python.org>
parents: 45987
diff changeset
65 Failing imports remove incomplete module objects.
44797
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
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
68 The function is an alias for :c:func:`PyImport_ImportModuleLevel` with
44797
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
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
72 .. c:function:: PyObject* PyImport_ImportModuleLevel(char *name, PyObject *globals, PyObject *locals, PyObject *fromlist, int level)
44797
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
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
86 .. c:function:: PyObject* PyImport_Import(PyObject *name)
44797
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
56814
127d623396ab Merged revisions 73286,73294,73296,73459,73462-73463,73544,73576-73577,73595-73596,73693-73694,73704-73705,73707,73713,73937-73940,73945,73951,73979 via svnmerge from
Georg Brandl <georg@python.org>
parents: 45987
diff changeset
98 Always uses absolute imports.
44797
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
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
101 .. c:function:: PyObject* PyImport_ReloadModule(PyObject *m)
44797
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
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
111 .. c:function:: PyObject* PyImport_AddModule(const char *name)
44797
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
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
121 loaded, you will get an empty module object. Use :c:func:`PyImport_ImportModule`
44797
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
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
126 .. c:function:: PyObject* PyImport_ExecCodeModule(char *name, PyObject *co)
44797
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
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
136 in :attr:`sys.modules` on entry to :c:func:`PyImport_ExecCodeModule`. Leaving
44797
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
61699
6391055efca0 Merged revisions 79579-79580,79585-79587 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56818
diff changeset
141 The module's :attr:`__file__` attribute will be set to the code object's
74398
9f664e163c9d how could I have missed :cmember: in import.rst?
Sandro Tosi <sandro.tosi@gmail.com>
parents: 74395
diff changeset
142 :c:member:`co_filename`.
61699
6391055efca0 Merged revisions 79579-79580,79585-79587 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56818
diff changeset
143
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
144 This function will reload the module if it was already imported. See
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
145 :c:func:`PyImport_ReloadModule` for the intended way to reload a module.
44797
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 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
148 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
149
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
150 .. versionchanged:: 2.4
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
151 *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
152
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
153
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
154 .. c:function:: PyObject* PyImport_ExecCodeModuleEx(char *name, PyObject *co, char *pathname)
61699
6391055efca0 Merged revisions 79579-79580,79585-79587 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56818
diff changeset
155
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
156 Like :c:func:`PyImport_ExecCodeModule`, but the :attr:`__file__` attribute of
61699
6391055efca0 Merged revisions 79579-79580,79585-79587 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56818
diff changeset
157 the module object is set to *pathname* if it is non-``NULL``.
6391055efca0 Merged revisions 79579-79580,79585-79587 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56818
diff changeset
158
6391055efca0 Merged revisions 79579-79580,79585-79587 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56818
diff changeset
159
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
160 .. c:function:: long PyImport_GetMagicNumber()
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
161
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
162 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
163 :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
164 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
165
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
166
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
167 .. c:function:: PyObject* PyImport_GetModuleDict()
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
168
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
169 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
170 ``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
171
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
172
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
173 .. c:function:: PyObject* PyImport_GetImporter(PyObject *path)
45987
d6793ece3254 #2160: document PyImport_GetImporter.
Georg Brandl <georg@python.org>
parents: 44797
diff changeset
174
d6793ece3254 #2160: document PyImport_GetImporter.
Georg Brandl <georg@python.org>
parents: 44797
diff changeset
175 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
176 *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
177 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
178 is found that can handle the path item. Return ``None`` if no hook could;
56818
3e15a07a32fa Merged revisions 74209 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56814
diff changeset
179 this tells our caller it should fall back to the built-in import mechanism.
45987
d6793ece3254 #2160: document PyImport_GetImporter.
Georg Brandl <georg@python.org>
parents: 44797
diff changeset
180 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
181 to the importer object.
d6793ece3254 #2160: document PyImport_GetImporter.
Georg Brandl <georg@python.org>
parents: 44797
diff changeset
182
d6793ece3254 #2160: document PyImport_GetImporter.
Georg Brandl <georg@python.org>
parents: 44797
diff changeset
183 .. versionadded:: 2.6
d6793ece3254 #2160: document PyImport_GetImporter.
Georg Brandl <georg@python.org>
parents: 44797
diff changeset
184
d6793ece3254 #2160: document PyImport_GetImporter.
Georg Brandl <georg@python.org>
parents: 44797
diff changeset
185
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
186 .. c:function:: void _PyImport_Init()
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
187
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
188 Initialize the import mechanism. For internal use only.
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
189
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
190
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
191 .. c:function:: void PyImport_Cleanup()
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
192
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
193 Empty the module table. For internal use only.
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
194
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
195
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
196 .. c:function:: void _PyImport_Fini()
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
197
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
198 Finalize the import mechanism. For internal use only.
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
199
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
200
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
201 .. c:function:: PyObject* _PyImport_FindExtension(char *, char *)
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
202
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
203 For internal use only.
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
204
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
205
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
206 .. c:function:: PyObject* _PyImport_FixupExtension(char *, char *)
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
207
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
208 For internal use only.
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
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
211 .. c:function:: int PyImport_ImportFrozenModule(char *name)
44797
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 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
214 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
215 failed. To access the imported module on a successful load, use
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
216 :c:func:`PyImport_ImportModule`. (Note the misnomer --- this function would
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
217 reload the module if it was already imported.)
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
218
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
219
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
220 .. c:type:: struct _frozen
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
221
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
222 .. index:: single: freeze utility
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
223
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
224 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
225 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
226 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
227 is::
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 struct _frozen {
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
230 char *name;
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
231 unsigned char *code;
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
232 int size;
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
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
235
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
236 .. c:var:: struct _frozen* PyImport_FrozenModules
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
237
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
238 This pointer is initialized to point to an array of :c:type:`struct _frozen`
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
239 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
240 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
241 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
242
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
243
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
244 .. c:function:: 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
245
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
246 Add a single module to the existing table of built-in modules. This is a
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
247 convenience wrapper around :c:func:`PyImport_ExtendInittab`, returning ``-1`` if
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
248 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
249 *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
250 on the first attempted import. This should be called before
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
251 :c:func:`Py_Initialize`.
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
252
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
253
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
254 .. c:type:: struct _inittab
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
255
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
256 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
257 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
258 into the interpreter. Programs which embed Python may use an array of these
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
259 structures in conjunction with :c:func:`PyImport_ExtendInittab` to provide
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
260 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
261 :file:`Include/import.h` as::
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
262
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
263 struct _inittab {
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
264 char *name;
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
265 void (*initfunc)(void);
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
266 };
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
267
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
268
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
269 .. c:function:: int PyImport_ExtendInittab(struct _inittab *newtab)
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
270
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
271 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
272 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
273 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
274 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
275 extend the internal table. In the event of failure, no modules are added to the
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
276 internal table. This should be called before :c:func:`Py_Initialize`.