Mercurial > cpython-lru_cache-weakref
annotate Doc/lib/libimp.tex @ 27998:e27f58a50737 legacy-trunk
SF bug #690377: Dud footnote reference in distutils docs
| author | Raymond Hettinger <python@rcn.com> |
|---|---|
| date | Fri, 21 Feb 2003 02:47:09 +0000 |
| parents | 5620b0786271 |
| children | c9b99308b0e8 |
| rev | line source |
|---|---|
| 8918 | 1 \section{\module{imp} --- |
| 10699 | 2 Access the \keyword{import} internals} |
| 3 | |
|
8716
760dcf197048
Adjusted to use the new module synopsis support macros.
Fred Drake <fdrake@acm.org>
parents:
7877
diff
changeset
|
4 \declaremodule{builtin}{imp} |
|
760dcf197048
Adjusted to use the new module synopsis support macros.
Fred Drake <fdrake@acm.org>
parents:
7877
diff
changeset
|
5 \modulesynopsis{Access the implementation of the \keyword{import} statement.} |
|
760dcf197048
Adjusted to use the new module synopsis support macros.
Fred Drake <fdrake@acm.org>
parents:
7877
diff
changeset
|
6 |
| 2110 | 7 |
|
10966
259237b25b93
Improve index entry for "import"; responding to comments by Stefan
Fred Drake <fdrake@acm.org>
parents:
10699
diff
changeset
|
8 This\stindex{import} module provides an interface to the mechanisms |
| 10699 | 9 used to implement the \keyword{import} statement. It defines the |
| 10 following constants and functions: | |
| 2110 | 11 |
| 12 | |
| 13 \begin{funcdesc}{get_magic}{} | |
| 8935 | 14 \indexii{file}{byte-code} |
|
2576
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2527
diff
changeset
|
15 Return the magic string value used to recognize byte-compiled code |
| 8935 | 16 files (\file{.pyc} files). (This value may be different for each |
|
6303
cf0effc3f585
Update the description and the example to the new functionality, which
Guido van Rossum <guido@python.org>
parents:
5818
diff
changeset
|
17 Python version.) |
| 2110 | 18 \end{funcdesc} |
| 19 | |
| 20 \begin{funcdesc}{get_suffixes}{} | |
|
6303
cf0effc3f585
Update the description and the example to the new functionality, which
Guido van Rossum <guido@python.org>
parents:
5818
diff
changeset
|
21 Return a list of triples, each describing a particular type of module. |
| 2110 | 22 Each triple has the form \code{(\var{suffix}, \var{mode}, |
| 23 \var{type})}, where \var{suffix} is a string to be appended to the | |
| 24 module name to form the filename to search for, \var{mode} is the mode | |
| 8935 | 25 string to pass to the built-in \function{open()} function to open the |
| 26 file (this can be \code{'r'} for text files or \code{'rb'} for binary | |
| 2110 | 27 files), and \var{type} is the file type, which has one of the values |
| 7606 | 28 \constant{PY_SOURCE}, \constant{PY_COMPILED}, or |
| 29 \constant{C_EXTENSION}, described below. | |
| 2110 | 30 \end{funcdesc} |
| 31 | |
| 7038 | 32 \begin{funcdesc}{find_module}{name\optional{, path}} |
|
6303
cf0effc3f585
Update the description and the example to the new functionality, which
Guido van Rossum <guido@python.org>
parents:
5818
diff
changeset
|
33 Try to find the module \var{name} on the search path \var{path}. If |
|
cf0effc3f585
Update the description and the example to the new functionality, which
Guido van Rossum <guido@python.org>
parents:
5818
diff
changeset
|
34 \var{path} is a list of directory names, each directory is searched |
| 7606 | 35 for files with any of the suffixes returned by \function{get_suffixes()} |
|
6303
cf0effc3f585
Update the description and the example to the new functionality, which
Guido van Rossum <guido@python.org>
parents:
5818
diff
changeset
|
36 above. Invalid names in the list are silently ignored (but all list |
|
cf0effc3f585
Update the description and the example to the new functionality, which
Guido van Rossum <guido@python.org>
parents:
5818
diff
changeset
|
37 items must be strings). If \var{path} is omitted or \code{None}, the |
|
cf0effc3f585
Update the description and the example to the new functionality, which
Guido van Rossum <guido@python.org>
parents:
5818
diff
changeset
|
38 list of directory names given by \code{sys.path} is searched, but |
|
cf0effc3f585
Update the description and the example to the new functionality, which
Guido van Rossum <guido@python.org>
parents:
5818
diff
changeset
|
39 first it searches a few special places: it tries to find a built-in |
| 7606 | 40 module with the given name (\constant{C_BUILTIN}), then a frozen module |
| 41 (\constant{PY_FROZEN}), and on some systems some other places are looked | |
| 42 in as well (on the Mac, it looks for a resource (\constant{PY_RESOURCE}); | |
|
6303
cf0effc3f585
Update the description and the example to the new functionality, which
Guido van Rossum <guido@python.org>
parents:
5818
diff
changeset
|
43 on Windows, it looks in the registry which may point to a specific |
|
cf0effc3f585
Update the description and the example to the new functionality, which
Guido van Rossum <guido@python.org>
parents:
5818
diff
changeset
|
44 file). |
|
cf0effc3f585
Update the description and the example to the new functionality, which
Guido van Rossum <guido@python.org>
parents:
5818
diff
changeset
|
45 |
|
cf0effc3f585
Update the description and the example to the new functionality, which
Guido van Rossum <guido@python.org>
parents:
5818
diff
changeset
|
46 If search is successful, the return value is a triple |
| 2110 | 47 \code{(\var{file}, \var{pathname}, \var{description})} where |
|
2576
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2527
diff
changeset
|
48 \var{file} is an open file object positioned at the beginning, |
|
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2527
diff
changeset
|
49 \var{pathname} is the pathname of the |
| 2110 | 50 file found, and \var{description} is a triple as contained in the list |
| 7606 | 51 returned by \function{get_suffixes()} describing the kind of module found. |
|
6303
cf0effc3f585
Update the description and the example to the new functionality, which
Guido van Rossum <guido@python.org>
parents:
5818
diff
changeset
|
52 If the module does not live in a file, the returned \var{file} is |
|
cf0effc3f585
Update the description and the example to the new functionality, which
Guido van Rossum <guido@python.org>
parents:
5818
diff
changeset
|
53 \code{None}, \var{filename} is the empty string, and the |
|
cf0effc3f585
Update the description and the example to the new functionality, which
Guido van Rossum <guido@python.org>
parents:
5818
diff
changeset
|
54 \var{description} tuple contains empty strings for its suffix and |
|
13625
fdfd1049f36e
Rob W. W. Hooft's spelling fixes for the Library Reference. I hope
Thomas Wouters <thomas@python.org>
parents:
10966
diff
changeset
|
55 mode; the module type is as indicate in parentheses above. If the |
| 7606 | 56 search is unsuccessful, \exception{ImportError} is raised. Other |
|
6303
cf0effc3f585
Update the description and the example to the new functionality, which
Guido van Rossum <guido@python.org>
parents:
5818
diff
changeset
|
57 exceptions indicate problems with the arguments or environment. |
|
cf0effc3f585
Update the description and the example to the new functionality, which
Guido van Rossum <guido@python.org>
parents:
5818
diff
changeset
|
58 |
|
cf0effc3f585
Update the description and the example to the new functionality, which
Guido van Rossum <guido@python.org>
parents:
5818
diff
changeset
|
59 This function does not handle hierarchical module names (names |
|
18411
eeb2e77c5bad
Fix up a few style nits -- avoid "e.g." and "i.e." -- these make
Fred Drake <fdrake@acm.org>
parents:
15928
diff
changeset
|
60 containing dots). In order to find \var{P}.\var{M}, that is, submodule |
| 7606 | 61 \var{M} of package \var{P}, use \function{find_module()} and |
| 62 \function{load_module()} to find and load package \var{P}, and then use | |
| 63 \function{find_module()} with the \var{path} argument set to | |
|
6303
cf0effc3f585
Update the description and the example to the new functionality, which
Guido van Rossum <guido@python.org>
parents:
5818
diff
changeset
|
64 \code{\var{P}.__path__}. When \var{P} itself has a dotted name, apply |
|
cf0effc3f585
Update the description and the example to the new functionality, which
Guido van Rossum <guido@python.org>
parents:
5818
diff
changeset
|
65 this recipe recursively. |
|
cf0effc3f585
Update the description and the example to the new functionality, which
Guido van Rossum <guido@python.org>
parents:
5818
diff
changeset
|
66 \end{funcdesc} |
|
cf0effc3f585
Update the description and the example to the new functionality, which
Guido van Rossum <guido@python.org>
parents:
5818
diff
changeset
|
67 |
|
cf0effc3f585
Update the description and the example to the new functionality, which
Guido van Rossum <guido@python.org>
parents:
5818
diff
changeset
|
68 \begin{funcdesc}{load_module}{name, file, filename, description} |
| 7606 | 69 Load a module that was previously found by \function{find_module()} (or by |
|
6303
cf0effc3f585
Update the description and the example to the new functionality, which
Guido van Rossum <guido@python.org>
parents:
5818
diff
changeset
|
70 an otherwise conducted search yielding compatible results). This |
|
cf0effc3f585
Update the description and the example to the new functionality, which
Guido van Rossum <guido@python.org>
parents:
5818
diff
changeset
|
71 function does more than importing the module: if the module was |
| 7606 | 72 already imported, it is equivalent to a |
|
15149
fdc2abdf4777
Fixed a large number of small problems, mostly noted by Detlef Lannert
Fred Drake <fdrake@acm.org>
parents:
13625
diff
changeset
|
73 \function{reload()}\bifuncindex{reload}! The \var{name} argument |
|
fdc2abdf4777
Fixed a large number of small problems, mostly noted by Detlef Lannert
Fred Drake <fdrake@acm.org>
parents:
13625
diff
changeset
|
74 indicates the full module name (including the package name, if this is |
|
fdc2abdf4777
Fixed a large number of small problems, mostly noted by Detlef Lannert
Fred Drake <fdrake@acm.org>
parents:
13625
diff
changeset
|
75 a submodule of a package). The \var{file} argument is an open file, |
|
fdc2abdf4777
Fixed a large number of small problems, mostly noted by Detlef Lannert
Fred Drake <fdrake@acm.org>
parents:
13625
diff
changeset
|
76 and \var{filename} is the corresponding file name; these can be |
|
fdc2abdf4777
Fixed a large number of small problems, mostly noted by Detlef Lannert
Fred Drake <fdrake@acm.org>
parents:
13625
diff
changeset
|
77 \code{None} and \code{''}, respectively, when the module is not being |
|
fdc2abdf4777
Fixed a large number of small problems, mostly noted by Detlef Lannert
Fred Drake <fdrake@acm.org>
parents:
13625
diff
changeset
|
78 loaded from a file. The \var{description} argument is a tuple, as |
|
fdc2abdf4777
Fixed a large number of small problems, mostly noted by Detlef Lannert
Fred Drake <fdrake@acm.org>
parents:
13625
diff
changeset
|
79 would be returned by \function{get_suffixes()}, describing what kind |
|
fdc2abdf4777
Fixed a large number of small problems, mostly noted by Detlef Lannert
Fred Drake <fdrake@acm.org>
parents:
13625
diff
changeset
|
80 of module must be loaded. |
|
6303
cf0effc3f585
Update the description and the example to the new functionality, which
Guido van Rossum <guido@python.org>
parents:
5818
diff
changeset
|
81 |
|
cf0effc3f585
Update the description and the example to the new functionality, which
Guido van Rossum <guido@python.org>
parents:
5818
diff
changeset
|
82 If the load is successful, the return value is the module object; |
| 7606 | 83 otherwise, an exception (usually \exception{ImportError}) is raised. |
|
6303
cf0effc3f585
Update the description and the example to the new functionality, which
Guido van Rossum <guido@python.org>
parents:
5818
diff
changeset
|
84 |
|
cf0effc3f585
Update the description and the example to the new functionality, which
Guido van Rossum <guido@python.org>
parents:
5818
diff
changeset
|
85 \strong{Important:} the caller is responsible for closing the |
|
cf0effc3f585
Update the description and the example to the new functionality, which
Guido van Rossum <guido@python.org>
parents:
5818
diff
changeset
|
86 \var{file} argument, if it was not \code{None}, even when an exception |
| 7606 | 87 is raised. This is best done using a \keyword{try} |
| 88 ... \keyword{finally} statement. | |
| 2110 | 89 \end{funcdesc} |
| 90 | |
|
6303
cf0effc3f585
Update the description and the example to the new functionality, which
Guido van Rossum <guido@python.org>
parents:
5818
diff
changeset
|
91 \begin{funcdesc}{new_module}{name} |
|
cf0effc3f585
Update the description and the example to the new functionality, which
Guido van Rossum <guido@python.org>
parents:
5818
diff
changeset
|
92 Return a new empty module object called \var{name}. This object is |
| 7038 | 93 \emph{not} inserted in \code{sys.modules}. |
|
6303
cf0effc3f585
Update the description and the example to the new functionality, which
Guido van Rossum <guido@python.org>
parents:
5818
diff
changeset
|
94 \end{funcdesc} |
|
cf0effc3f585
Update the description and the example to the new functionality, which
Guido van Rossum <guido@python.org>
parents:
5818
diff
changeset
|
95 |
|
19596
1be18ef869a4
Add a new function imp.lock_held(), and use it to skip test_threaded_import
Tim Peters <tim.peters@gmail.com>
parents:
18411
diff
changeset
|
96 \begin{funcdesc}{lock_held}{} |
|
22920
2392af05f052
Update docs for bool changes by Guido around April 6
Neal Norwitz <nnorwitz@gmail.com>
parents:
22878
diff
changeset
|
97 Return \code{True} if the import lock is currently held, else \code{False}. |
|
2392af05f052
Update docs for bool changes by Guido around April 6
Neal Norwitz <nnorwitz@gmail.com>
parents:
22878
diff
changeset
|
98 On platforms without threads, always return \code{False}. |
|
19596
1be18ef869a4
Add a new function imp.lock_held(), and use it to skip test_threaded_import
Tim Peters <tim.peters@gmail.com>
parents:
18411
diff
changeset
|
99 |
|
1be18ef869a4
Add a new function imp.lock_held(), and use it to skip test_threaded_import
Tim Peters <tim.peters@gmail.com>
parents:
18411
diff
changeset
|
100 On platforms with threads, a thread executing an import holds an internal |
|
1be18ef869a4
Add a new function imp.lock_held(), and use it to skip test_threaded_import
Tim Peters <tim.peters@gmail.com>
parents:
18411
diff
changeset
|
101 lock until the import is complete. |
|
1be18ef869a4
Add a new function imp.lock_held(), and use it to skip test_threaded_import
Tim Peters <tim.peters@gmail.com>
parents:
18411
diff
changeset
|
102 This lock blocks other threads from doing an import until the original |
|
1be18ef869a4
Add a new function imp.lock_held(), and use it to skip test_threaded_import
Tim Peters <tim.peters@gmail.com>
parents:
18411
diff
changeset
|
103 import completes, which in turn prevents other threads from seeing |
|
1be18ef869a4
Add a new function imp.lock_held(), and use it to skip test_threaded_import
Tim Peters <tim.peters@gmail.com>
parents:
18411
diff
changeset
|
104 incomplete module objects constructed by the original thread while in |
|
1be18ef869a4
Add a new function imp.lock_held(), and use it to skip test_threaded_import
Tim Peters <tim.peters@gmail.com>
parents:
18411
diff
changeset
|
105 the process of completing its import (and the imports, if any, |
|
1be18ef869a4
Add a new function imp.lock_held(), and use it to skip test_threaded_import
Tim Peters <tim.peters@gmail.com>
parents:
18411
diff
changeset
|
106 triggered by that). |
|
1be18ef869a4
Add a new function imp.lock_held(), and use it to skip test_threaded_import
Tim Peters <tim.peters@gmail.com>
parents:
18411
diff
changeset
|
107 \end{funcdesc} |
|
1be18ef869a4
Add a new function imp.lock_held(), and use it to skip test_threaded_import
Tim Peters <tim.peters@gmail.com>
parents:
18411
diff
changeset
|
108 |
|
27853
5620b0786271
Cleanup from patch #683257:
Neal Norwitz <nnorwitz@gmail.com>
parents:
26796
diff
changeset
|
109 \begin{funcdesc}{acquire_lock}{} |
|
5620b0786271
Cleanup from patch #683257:
Neal Norwitz <nnorwitz@gmail.com>
parents:
26796
diff
changeset
|
110 Acquires the interpreter's import lock for the current thread. This lock |
|
5620b0786271
Cleanup from patch #683257:
Neal Norwitz <nnorwitz@gmail.com>
parents:
26796
diff
changeset
|
111 should be used by import hooks to ensure thread-safety when importing modules. |
|
5620b0786271
Cleanup from patch #683257:
Neal Norwitz <nnorwitz@gmail.com>
parents:
26796
diff
changeset
|
112 On platforms without threads, this function does nothing. |
|
5620b0786271
Cleanup from patch #683257:
Neal Norwitz <nnorwitz@gmail.com>
parents:
26796
diff
changeset
|
113 \versionadded{2.3} |
|
5620b0786271
Cleanup from patch #683257:
Neal Norwitz <nnorwitz@gmail.com>
parents:
26796
diff
changeset
|
114 \end{funcdesc} |
|
5620b0786271
Cleanup from patch #683257:
Neal Norwitz <nnorwitz@gmail.com>
parents:
26796
diff
changeset
|
115 |
|
5620b0786271
Cleanup from patch #683257:
Neal Norwitz <nnorwitz@gmail.com>
parents:
26796
diff
changeset
|
116 \begin{funcdesc}{release_lock}{} |
|
5620b0786271
Cleanup from patch #683257:
Neal Norwitz <nnorwitz@gmail.com>
parents:
26796
diff
changeset
|
117 Release the interpreter's import lock. |
|
5620b0786271
Cleanup from patch #683257:
Neal Norwitz <nnorwitz@gmail.com>
parents:
26796
diff
changeset
|
118 On platforms without threads, this function does nothing. |
|
5620b0786271
Cleanup from patch #683257:
Neal Norwitz <nnorwitz@gmail.com>
parents:
26796
diff
changeset
|
119 \versionadded{2.3} |
|
5620b0786271
Cleanup from patch #683257:
Neal Norwitz <nnorwitz@gmail.com>
parents:
26796
diff
changeset
|
120 \end{funcdesc} |
|
5620b0786271
Cleanup from patch #683257:
Neal Norwitz <nnorwitz@gmail.com>
parents:
26796
diff
changeset
|
121 |
|
6303
cf0effc3f585
Update the description and the example to the new functionality, which
Guido van Rossum <guido@python.org>
parents:
5818
diff
changeset
|
122 The following constants with integer values, defined in this module, |
| 7606 | 123 are used to indicate the search result of \function{find_module()}. |
|
6303
cf0effc3f585
Update the description and the example to the new functionality, which
Guido van Rossum <guido@python.org>
parents:
5818
diff
changeset
|
124 |
|
cf0effc3f585
Update the description and the example to the new functionality, which
Guido van Rossum <guido@python.org>
parents:
5818
diff
changeset
|
125 \begin{datadesc}{PY_SOURCE} |
|
cf0effc3f585
Update the description and the example to the new functionality, which
Guido van Rossum <guido@python.org>
parents:
5818
diff
changeset
|
126 The module was found as a source file. |
|
cf0effc3f585
Update the description and the example to the new functionality, which
Guido van Rossum <guido@python.org>
parents:
5818
diff
changeset
|
127 \end{datadesc} |
|
cf0effc3f585
Update the description and the example to the new functionality, which
Guido van Rossum <guido@python.org>
parents:
5818
diff
changeset
|
128 |
|
cf0effc3f585
Update the description and the example to the new functionality, which
Guido van Rossum <guido@python.org>
parents:
5818
diff
changeset
|
129 \begin{datadesc}{PY_COMPILED} |
|
cf0effc3f585
Update the description and the example to the new functionality, which
Guido van Rossum <guido@python.org>
parents:
5818
diff
changeset
|
130 The module was found as a compiled code object file. |
|
cf0effc3f585
Update the description and the example to the new functionality, which
Guido van Rossum <guido@python.org>
parents:
5818
diff
changeset
|
131 \end{datadesc} |
|
cf0effc3f585
Update the description and the example to the new functionality, which
Guido van Rossum <guido@python.org>
parents:
5818
diff
changeset
|
132 |
|
cf0effc3f585
Update the description and the example to the new functionality, which
Guido van Rossum <guido@python.org>
parents:
5818
diff
changeset
|
133 \begin{datadesc}{C_EXTENSION} |
|
cf0effc3f585
Update the description and the example to the new functionality, which
Guido van Rossum <guido@python.org>
parents:
5818
diff
changeset
|
134 The module was found as dynamically loadable shared library. |
|
cf0effc3f585
Update the description and the example to the new functionality, which
Guido van Rossum <guido@python.org>
parents:
5818
diff
changeset
|
135 \end{datadesc} |
|
cf0effc3f585
Update the description and the example to the new functionality, which
Guido van Rossum <guido@python.org>
parents:
5818
diff
changeset
|
136 |
|
cf0effc3f585
Update the description and the example to the new functionality, which
Guido van Rossum <guido@python.org>
parents:
5818
diff
changeset
|
137 \begin{datadesc}{PY_RESOURCE} |
|
cf0effc3f585
Update the description and the example to the new functionality, which
Guido van Rossum <guido@python.org>
parents:
5818
diff
changeset
|
138 The module was found as a Macintosh resource. This value can only be |
|
cf0effc3f585
Update the description and the example to the new functionality, which
Guido van Rossum <guido@python.org>
parents:
5818
diff
changeset
|
139 returned on a Macintosh. |
|
cf0effc3f585
Update the description and the example to the new functionality, which
Guido van Rossum <guido@python.org>
parents:
5818
diff
changeset
|
140 \end{datadesc} |
|
cf0effc3f585
Update the description and the example to the new functionality, which
Guido van Rossum <guido@python.org>
parents:
5818
diff
changeset
|
141 |
|
cf0effc3f585
Update the description and the example to the new functionality, which
Guido van Rossum <guido@python.org>
parents:
5818
diff
changeset
|
142 \begin{datadesc}{PKG_DIRECTORY} |
|
cf0effc3f585
Update the description and the example to the new functionality, which
Guido van Rossum <guido@python.org>
parents:
5818
diff
changeset
|
143 The module was found as a package directory. |
|
cf0effc3f585
Update the description and the example to the new functionality, which
Guido van Rossum <guido@python.org>
parents:
5818
diff
changeset
|
144 \end{datadesc} |
|
cf0effc3f585
Update the description and the example to the new functionality, which
Guido van Rossum <guido@python.org>
parents:
5818
diff
changeset
|
145 |
|
cf0effc3f585
Update the description and the example to the new functionality, which
Guido van Rossum <guido@python.org>
parents:
5818
diff
changeset
|
146 \begin{datadesc}{C_BUILTIN} |
|
cf0effc3f585
Update the description and the example to the new functionality, which
Guido van Rossum <guido@python.org>
parents:
5818
diff
changeset
|
147 The module was found as a built-in module. |
|
cf0effc3f585
Update the description and the example to the new functionality, which
Guido van Rossum <guido@python.org>
parents:
5818
diff
changeset
|
148 \end{datadesc} |
|
cf0effc3f585
Update the description and the example to the new functionality, which
Guido van Rossum <guido@python.org>
parents:
5818
diff
changeset
|
149 |
|
cf0effc3f585
Update the description and the example to the new functionality, which
Guido van Rossum <guido@python.org>
parents:
5818
diff
changeset
|
150 \begin{datadesc}{PY_FROZEN} |
| 7606 | 151 The module was found as a frozen module (see \function{init_frozen()}). |
|
6303
cf0effc3f585
Update the description and the example to the new functionality, which
Guido van Rossum <guido@python.org>
parents:
5818
diff
changeset
|
152 \end{datadesc} |
|
cf0effc3f585
Update the description and the example to the new functionality, which
Guido van Rossum <guido@python.org>
parents:
5818
diff
changeset
|
153 |
|
cf0effc3f585
Update the description and the example to the new functionality, which
Guido van Rossum <guido@python.org>
parents:
5818
diff
changeset
|
154 The following constant and functions are obsolete; their functionality |
| 7606 | 155 is available through \function{find_module()} or \function{load_module()}. |
|
6303
cf0effc3f585
Update the description and the example to the new functionality, which
Guido van Rossum <guido@python.org>
parents:
5818
diff
changeset
|
156 They are kept around for backward compatibility: |
|
cf0effc3f585
Update the description and the example to the new functionality, which
Guido van Rossum <guido@python.org>
parents:
5818
diff
changeset
|
157 |
|
cf0effc3f585
Update the description and the example to the new functionality, which
Guido van Rossum <guido@python.org>
parents:
5818
diff
changeset
|
158 \begin{datadesc}{SEARCH_ERROR} |
|
cf0effc3f585
Update the description and the example to the new functionality, which
Guido van Rossum <guido@python.org>
parents:
5818
diff
changeset
|
159 Unused. |
|
cf0effc3f585
Update the description and the example to the new functionality, which
Guido van Rossum <guido@python.org>
parents:
5818
diff
changeset
|
160 \end{datadesc} |
|
cf0effc3f585
Update the description and the example to the new functionality, which
Guido van Rossum <guido@python.org>
parents:
5818
diff
changeset
|
161 |
| 2110 | 162 \begin{funcdesc}{init_builtin}{name} |
| 163 Initialize the built-in module called \var{name} and return its module | |
| 164 object. If the module was already initialized, it will be initialized | |
| 7038 | 165 \emph{again}. A few modules cannot be initialized twice --- attempting |
| 7606 | 166 to initialize these again will raise an \exception{ImportError} |
| 167 exception. If there is no | |
| 2110 | 168 built-in module called \var{name}, \code{None} is returned. |
| 169 \end{funcdesc} | |
| 170 | |
| 171 \begin{funcdesc}{init_frozen}{name} | |
| 172 Initialize the frozen module called \var{name} and return its module | |
| 173 object. If the module was already initialized, it will be initialized | |
| 7038 | 174 \emph{again}. If there is no frozen module called \var{name}, |
| 2110 | 175 \code{None} is returned. (Frozen modules are modules written in |
| 176 Python whose compiled byte-code object is incorporated into a | |
| 7606 | 177 custom-built Python interpreter by Python's \program{freeze} utility. |
| 178 See \file{Tools/freeze/} for now.) | |
| 2110 | 179 \end{funcdesc} |
| 180 | |
| 181 \begin{funcdesc}{is_builtin}{name} | |
| 7606 | 182 Return \code{1} if there is a built-in module called \var{name} which |
| 183 can be initialized again. Return \code{-1} if there is a built-in | |
| 184 module called \var{name} which cannot be initialized again (see | |
| 185 \function{init_builtin()}). Return \code{0} if there is no built-in | |
| 186 module called \var{name}. | |
| 2110 | 187 \end{funcdesc} |
| 188 | |
| 189 \begin{funcdesc}{is_frozen}{name} | |
|
22920
2392af05f052
Update docs for bool changes by Guido around April 6
Neal Norwitz <nnorwitz@gmail.com>
parents:
22878
diff
changeset
|
190 Return \code{True} if there is a frozen module (see |
|
2392af05f052
Update docs for bool changes by Guido around April 6
Neal Norwitz <nnorwitz@gmail.com>
parents:
22878
diff
changeset
|
191 \function{init_frozen()}) called \var{name}, or \code{False} if there is |
| 7606 | 192 no such module. |
| 2110 | 193 \end{funcdesc} |
| 194 | |
| 7038 | 195 \begin{funcdesc}{load_compiled}{name, pathname, file} |
| 8935 | 196 \indexii{file}{byte-code} |
| 2110 | 197 Load and initialize a module implemented as a byte-compiled code file |
| 198 and return its module object. If the module was already initialized, | |
| 7038 | 199 it will be initialized \emph{again}. The \var{name} argument is used |
| 2110 | 200 to create or access a module object. The \var{pathname} argument |
|
3709
dad4d43363d8
Slight update; file args are no longer optional.
Guido van Rossum <guido@python.org>
parents:
2943
diff
changeset
|
201 points to the byte-compiled code file. The \var{file} |
| 2110 | 202 argument is the byte-compiled code file, open for reading in binary |
|
3709
dad4d43363d8
Slight update; file args are no longer optional.
Guido van Rossum <guido@python.org>
parents:
2943
diff
changeset
|
203 mode, from the beginning. |
|
dad4d43363d8
Slight update; file args are no longer optional.
Guido van Rossum <guido@python.org>
parents:
2943
diff
changeset
|
204 It must currently be a real file object, not a |
| 2110 | 205 user-defined class emulating a file. |
| 206 \end{funcdesc} | |
| 207 | |
| 7038 | 208 \begin{funcdesc}{load_dynamic}{name, pathname\optional{, file}} |
| 2110 | 209 Load and initialize a module implemented as a dynamically loadable |
| 210 shared library and return its module object. If the module was | |
| 7038 | 211 already initialized, it will be initialized \emph{again}. Some modules |
| 2110 | 212 don't like that and may raise an exception. The \var{pathname} |
| 213 argument must point to the shared library. The \var{name} argument is | |
| 214 used to construct the name of the initialization function: an external | |
| 7606 | 215 C function called \samp{init\var{name}()} in the shared library is |
|
13625
fdfd1049f36e
Rob W. W. Hooft's spelling fixes for the Library Reference. I hope
Thomas Wouters <thomas@python.org>
parents:
10966
diff
changeset
|
216 called. The optional \var{file} argument is ignored. (Note: using |
| 2110 | 217 shared libraries is highly system dependent, and not all systems |
| 218 support it.) | |
| 219 \end{funcdesc} | |
| 220 | |
|
7712
0cbc9df882b6
Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents:
7606
diff
changeset
|
221 \begin{funcdesc}{load_source}{name, pathname, file} |
| 2110 | 222 Load and initialize a module implemented as a Python source file and |
| 223 return its module object. If the module was already initialized, it | |
| 7038 | 224 will be initialized \emph{again}. The \var{name} argument is used to |
| 2110 | 225 create or access a module object. The \var{pathname} argument points |
|
3709
dad4d43363d8
Slight update; file args are no longer optional.
Guido van Rossum <guido@python.org>
parents:
2943
diff
changeset
|
226 to the source file. The \var{file} argument is the source |
|
dad4d43363d8
Slight update; file args are no longer optional.
Guido van Rossum <guido@python.org>
parents:
2943
diff
changeset
|
227 file, open for reading as text, from the beginning. |
|
dad4d43363d8
Slight update; file args are no longer optional.
Guido van Rossum <guido@python.org>
parents:
2943
diff
changeset
|
228 It must currently be a real file |
| 2110 | 229 object, not a user-defined class emulating a file. Note that if a |
| 8935 | 230 properly matching byte-compiled file (with suffix \file{.pyc} or |
| 231 \file{.pyo}) exists, it will be used instead of parsing the given | |
| 232 source file. | |
| 2110 | 233 \end{funcdesc} |
| 234 | |
|
7400
685c510e14ce
Added \label{} for logical addressing.
Fred Drake <fdrake@acm.org>
parents:
7277
diff
changeset
|
235 |
| 2110 | 236 \subsection{Examples} |
|
7400
685c510e14ce
Added \label{} for logical addressing.
Fred Drake <fdrake@acm.org>
parents:
7277
diff
changeset
|
237 \label{examples-imp} |
|
685c510e14ce
Added \label{} for logical addressing.
Fred Drake <fdrake@acm.org>
parents:
7277
diff
changeset
|
238 |
|
6303
cf0effc3f585
Update the description and the example to the new functionality, which
Guido van Rossum <guido@python.org>
parents:
5818
diff
changeset
|
239 The following function emulates what was the standard import statement |
|
18411
eeb2e77c5bad
Fix up a few style nits -- avoid "e.g." and "i.e." -- these make
Fred Drake <fdrake@acm.org>
parents:
15928
diff
changeset
|
240 up to Python 1.4 (no hierarchical module names). (This |
|
6303
cf0effc3f585
Update the description and the example to the new functionality, which
Guido van Rossum <guido@python.org>
parents:
5818
diff
changeset
|
241 \emph{implementation} wouldn't work in that version, since |
| 7606 | 242 \function{find_module()} has been extended and |
| 243 \function{load_module()} has been added in 1.4.) | |
| 2110 | 244 |
|
7277
bf4e790bd61a
Remove all \bcode / \ecode cruft; this is no longer needed. See previous
Fred Drake <fdrake@acm.org>
parents:
7038
diff
changeset
|
245 \begin{verbatim} |
|
15928
1872e609a634
Add a missing newline in an example; caught by Chris Ryland
Fred Drake <fdrake@acm.org>
parents:
15149
diff
changeset
|
246 import imp |
|
1872e609a634
Add a missing newline in an example; caught by Chris Ryland
Fred Drake <fdrake@acm.org>
parents:
15149
diff
changeset
|
247 import sys |
| 2110 | 248 |
|
2345
9552edb4eabf
make __import__ 4-args
Guido van Rossum <guido@python.org>
parents:
2110
diff
changeset
|
249 def __import__(name, globals=None, locals=None, fromlist=None): |
|
2576
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2527
diff
changeset
|
250 # Fast path: see if the module has already been imported. |
|
6303
cf0effc3f585
Update the description and the example to the new functionality, which
Guido van Rossum <guido@python.org>
parents:
5818
diff
changeset
|
251 try: |
|
2576
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2527
diff
changeset
|
252 return sys.modules[name] |
|
6303
cf0effc3f585
Update the description and the example to the new functionality, which
Guido van Rossum <guido@python.org>
parents:
5818
diff
changeset
|
253 except KeyError: |
|
cf0effc3f585
Update the description and the example to the new functionality, which
Guido van Rossum <guido@python.org>
parents:
5818
diff
changeset
|
254 pass |
| 2110 | 255 |
|
2576
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2527
diff
changeset
|
256 # If any of the following calls raises an exception, |
|
2647
9b7e6d9a528d
typos, layout and other small things
Guido van Rossum <guido@python.org>
parents:
2609
diff
changeset
|
257 # there's a problem we can't handle -- let the caller handle it. |
|
2576
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2527
diff
changeset
|
258 |
|
6303
cf0effc3f585
Update the description and the example to the new functionality, which
Guido van Rossum <guido@python.org>
parents:
5818
diff
changeset
|
259 fp, pathname, description = imp.find_module(name) |
|
cf0effc3f585
Update the description and the example to the new functionality, which
Guido van Rossum <guido@python.org>
parents:
5818
diff
changeset
|
260 |
|
2818
c9b7297a0758
fix bug in example (should close file at all times)
Guido van Rossum <guido@python.org>
parents:
2647
diff
changeset
|
261 try: |
|
6303
cf0effc3f585
Update the description and the example to the new functionality, which
Guido van Rossum <guido@python.org>
parents:
5818
diff
changeset
|
262 return imp.load_module(name, fp, pathname, description) |
|
2818
c9b7297a0758
fix bug in example (should close file at all times)
Guido van Rossum <guido@python.org>
parents:
2647
diff
changeset
|
263 finally: |
|
c9b7297a0758
fix bug in example (should close file at all times)
Guido van Rossum <guido@python.org>
parents:
2647
diff
changeset
|
264 # Since we may exit via an exception, close fp explicitly. |
|
6303
cf0effc3f585
Update the description and the example to the new functionality, which
Guido van Rossum <guido@python.org>
parents:
5818
diff
changeset
|
265 if fp: |
|
cf0effc3f585
Update the description and the example to the new functionality, which
Guido van Rossum <guido@python.org>
parents:
5818
diff
changeset
|
266 fp.close() |
|
7277
bf4e790bd61a
Remove all \bcode / \ecode cruft; this is no longer needed. See previous
Fred Drake <fdrake@acm.org>
parents:
7038
diff
changeset
|
267 \end{verbatim} |
|
6303
cf0effc3f585
Update the description and the example to the new functionality, which
Guido van Rossum <guido@python.org>
parents:
5818
diff
changeset
|
268 |
|
cf0effc3f585
Update the description and the example to the new functionality, which
Guido van Rossum <guido@python.org>
parents:
5818
diff
changeset
|
269 A more complete example that implements hierarchical module names and |
| 7606 | 270 includes a \function{reload()}\bifuncindex{reload} function can be |
|
22878
3a6718b9b65a
Do not call "knee" a standard module, and point to the new location.
Fred Drake <fdrake@acm.org>
parents:
19596
diff
changeset
|
271 found in the module \module{knee}\refmodindex{knee}. The |
|
3a6718b9b65a
Do not call "knee" a standard module, and point to the new location.
Fred Drake <fdrake@acm.org>
parents:
19596
diff
changeset
|
272 \module{knee} module can be found in \file{Demo/imputil/} in the |
|
3a6718b9b65a
Do not call "knee" a standard module, and point to the new location.
Fred Drake <fdrake@acm.org>
parents:
19596
diff
changeset
|
273 Python source distribution. |