Mercurial > cpython-lru_cache-weakref
annotate Doc/libimp.tex @ 4566:6403c94de50d legacy-trunk
Added safeguard against failure in __del__.
| author | Guido van Rossum <guido@python.org> |
|---|---|
| date | Wed, 27 Nov 1996 19:39:58 +0000 |
| parents | dad4d43363d8 |
| children | 3468ea8645ca |
| rev | line source |
|---|---|
|
2576
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2527
diff
changeset
|
1 \section{Built-in Module \sectcode{imp}} |
| 2110 | 2 \bimodindex{imp} |
| 3 \index{import} | |
| 4 | |
|
2491
fb8e08ec88dd
changes (suggested) by Soren Larsen
Guido van Rossum <guido@python.org>
parents:
2453
diff
changeset
|
5 This module provides an interface to the mechanisms used to implement |
| 2110 | 6 the \code{import} statement. It defines the following constants and |
| 7 functions: | |
| 8 | |
| 2943 | 9 \renewcommand{\indexsubitem}{(in module imp)} |
| 2110 | 10 |
| 11 \begin{funcdesc}{get_magic}{} | |
|
2576
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2527
diff
changeset
|
12 Return the magic string value used to recognize byte-compiled code |
| 2110 | 13 files (``\code{.pyc} files''). |
| 14 \end{funcdesc} | |
| 15 | |
| 16 \begin{funcdesc}{get_suffixes}{} | |
| 17 Return a list of triples, each describing a particular type of file. | |
| 18 Each triple has the form \code{(\var{suffix}, \var{mode}, | |
| 19 \var{type})}, where \var{suffix} is a string to be appended to the | |
| 20 module name to form the filename to search for, \var{mode} is the mode | |
| 21 string to pass to the built-in \code{open} function to open the file | |
| 22 (this can be \code{'r'} for text files or \code{'rb'} for binary | |
| 23 files), and \var{type} is the file type, which has one of the values | |
| 24 \code{PY_SOURCE}, \code{PY_COMPILED} or \code{C_EXTENSION}, defined | |
|
2576
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2527
diff
changeset
|
25 below. (System-dependent values may also be returned.) |
| 2110 | 26 \end{funcdesc} |
| 27 | |
| 28 \begin{funcdesc}{find_module}{name\, \optional{path}} | |
| 29 Try to find the module \var{name} on the search path \var{path}. The | |
| 30 default \var{path} is \code{sys.path}. The return value is a triple | |
| 31 \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
|
32 \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
|
33 \var{pathname} is the pathname of the |
| 2110 | 34 file found, and \var{description} is a triple as contained in the list |
| 35 returned by \code{get_suffixes} describing the kind of file found. | |
| 36 \end{funcdesc} | |
| 37 | |
| 38 \begin{funcdesc}{init_builtin}{name} | |
| 39 Initialize the built-in module called \var{name} and return its module | |
| 40 object. If the module was already initialized, it will be initialized | |
|
2453
cdd3a721b40e
a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents:
2345
diff
changeset
|
41 {\em again}. A few modules cannot be initialized twice --- attempting |
|
2527
815dfaa6a778
small changes by Soren Larsen
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
42 to initialize these again will raise an \code{ImportError} exception. |
|
815dfaa6a778
small changes by Soren Larsen
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
43 If there is no |
| 2110 | 44 built-in module called \var{name}, \code{None} is returned. |
| 45 \end{funcdesc} | |
| 46 | |
| 47 \begin{funcdesc}{init_frozen}{name} | |
| 48 Initialize the frozen module called \var{name} and return its module | |
| 49 object. If the module was already initialized, it will be initialized | |
| 50 {\em again}. If there is no frozen module called \var{name}, | |
| 51 \code{None} is returned. (Frozen modules are modules written in | |
| 52 Python whose compiled byte-code object is incorporated into a | |
| 53 custom-built Python interpreter by Python's \code{freeze} utility. | |
|
2609
7ef72873e4d6
restructured library manual accordiung to functional group
Guido van Rossum <guido@python.org>
parents:
2576
diff
changeset
|
54 See \code{Tools/freeze} for now.) |
| 2110 | 55 \end{funcdesc} |
| 56 | |
| 57 \begin{funcdesc}{is_builtin}{name} | |
| 58 Return \code{1} if there is a built-in module called \var{name} which can be | |
| 59 initialized again. Return \code{-1} if there is a built-in module | |
| 60 called \var{name} which cannot be initialized again (see | |
| 61 \code{init_builtin}). Return \code{0} if there is no built-in module | |
| 62 called \var{name}. | |
| 63 \end{funcdesc} | |
| 64 | |
| 65 \begin{funcdesc}{is_frozen}{name} | |
| 66 Return \code{1} if there is a frozen module (see \code{init_frozen}) | |
| 67 called \var{name}, \code{0} if there is no such module. | |
| 68 \end{funcdesc} | |
| 69 | |
|
3709
dad4d43363d8
Slight update; file args are no longer optional.
Guido van Rossum <guido@python.org>
parents:
2943
diff
changeset
|
70 \begin{funcdesc}{load_compiled}{name\, pathname\, file} |
| 2110 | 71 Load and initialize a module implemented as a byte-compiled code file |
| 72 and return its module object. If the module was already initialized, | |
| 73 it will be initialized {\em again}. The \var{name} argument is used | |
| 74 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
|
75 points to the byte-compiled code file. The \var{file} |
| 2110 | 76 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
|
77 mode, from the beginning. |
|
dad4d43363d8
Slight update; file args are no longer optional.
Guido van Rossum <guido@python.org>
parents:
2943
diff
changeset
|
78 It must currently be a real file object, not a |
| 2110 | 79 user-defined class emulating a file. |
| 80 \end{funcdesc} | |
| 81 | |
| 82 \begin{funcdesc}{load_dynamic}{name\, pathname\, \optional{file}} | |
| 83 Load and initialize a module implemented as a dynamically loadable | |
| 84 shared library and return its module object. If the module was | |
| 85 already initialized, it will be initialized {\em again}. Some modules | |
| 86 don't like that and may raise an exception. The \var{pathname} | |
| 87 argument must point to the shared library. The \var{name} argument is | |
| 88 used to construct the name of the initialization function: an external | |
| 89 C function called \code{init\var{name}()} in the shared library is | |
| 90 called. The optional \var{file} argment is ignored. (Note: using | |
| 91 shared libraries is highly system dependent, and not all systems | |
| 92 support it.) | |
| 93 \end{funcdesc} | |
| 94 | |
|
3709
dad4d43363d8
Slight update; file args are no longer optional.
Guido van Rossum <guido@python.org>
parents:
2943
diff
changeset
|
95 \begin{funcdesc}{load_source}{name\, pathname\, file} |
| 2110 | 96 Load and initialize a module implemented as a Python source file and |
| 97 return its module object. If the module was already initialized, it | |
| 98 will be initialized {\em again}. The \var{name} argument is used to | |
| 99 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
|
100 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
|
101 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
|
102 It must currently be a real file |
| 2110 | 103 object, not a user-defined class emulating a file. Note that if a |
| 104 properly matching byte-compiled file (with suffix \code{.pyc}) exists, | |
| 105 it will be used instead of parsing the given source file. | |
| 106 \end{funcdesc} | |
| 107 | |
| 108 \begin{funcdesc}{new_module}{name} | |
| 109 Return a new empty module object called \var{name}. This object is | |
| 110 {\em not} inserted in \code{sys.modules}. | |
| 111 \end{funcdesc} | |
| 112 | |
| 113 The following constants with integer values, defined in the module, | |
| 114 are used to indicate the search result of \code{imp.find_module}. | |
| 115 | |
| 116 \begin{datadesc}{SEARCH_ERROR} | |
| 117 The module was not found. | |
| 118 \end{datadesc} | |
| 119 | |
| 120 \begin{datadesc}{PY_SOURCE} | |
| 121 The module was found as a source file. | |
| 122 \end{datadesc} | |
| 123 | |
| 124 \begin{datadesc}{PY_COMPILED} | |
| 125 The module was found as a compiled code object file. | |
| 126 \end{datadesc} | |
| 127 | |
| 128 \begin{datadesc}{C_EXTENSION} | |
| 129 The module was found as dynamically loadable shared library. | |
| 130 \end{datadesc} | |
| 131 | |
| 132 \subsection{Examples} | |
| 133 The following function emulates the default import statement: | |
| 134 | |
| 135 \begin{verbatim} | |
| 136 import imp | |
|
2576
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2527
diff
changeset
|
137 import sys |
| 2110 | 138 |
|
2345
9552edb4eabf
make __import__ 4-args
Guido van Rossum <guido@python.org>
parents:
2110
diff
changeset
|
139 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
|
140 # Fast path: see if the module has already been imported. |
|
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2527
diff
changeset
|
141 if sys.modules.has_key(name): |
|
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2527
diff
changeset
|
142 return sys.modules[name] |
| 2110 | 143 |
|
2576
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2527
diff
changeset
|
144 # 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
|
145 # 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
|
146 |
|
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2527
diff
changeset
|
147 # See if it's a built-in module. |
| 2110 | 148 m = imp.init_builtin(name) |
| 149 if m: | |
| 150 return m | |
| 151 | |
|
2576
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2527
diff
changeset
|
152 # See if it's a frozen module. |
| 2110 | 153 m = imp.init_frozen(name) |
| 154 if m: | |
| 155 return m | |
| 156 | |
| 157 # Search the default path (i.e. sys.path). | |
| 158 fp, pathname, (suffix, mode, type) = imp.find_module(name) | |
| 159 | |
| 160 # See what we got. | |
|
2818
c9b7297a0758
fix bug in example (should close file at all times)
Guido van Rossum <guido@python.org>
parents:
2647
diff
changeset
|
161 try: |
|
c9b7297a0758
fix bug in example (should close file at all times)
Guido van Rossum <guido@python.org>
parents:
2647
diff
changeset
|
162 if type == imp.C_EXTENSION: |
|
c9b7297a0758
fix bug in example (should close file at all times)
Guido van Rossum <guido@python.org>
parents:
2647
diff
changeset
|
163 return imp.load_dynamic(name, pathname) |
|
c9b7297a0758
fix bug in example (should close file at all times)
Guido van Rossum <guido@python.org>
parents:
2647
diff
changeset
|
164 if type == imp.PY_SOURCE: |
|
c9b7297a0758
fix bug in example (should close file at all times)
Guido van Rossum <guido@python.org>
parents:
2647
diff
changeset
|
165 return imp.load_source(name, pathname, fp) |
|
c9b7297a0758
fix bug in example (should close file at all times)
Guido van Rossum <guido@python.org>
parents:
2647
diff
changeset
|
166 if type == imp.PY_COMPILED: |
|
c9b7297a0758
fix bug in example (should close file at all times)
Guido van Rossum <guido@python.org>
parents:
2647
diff
changeset
|
167 return imp.load_compiled(name, pathname, fp) |
| 2110 | 168 |
|
2818
c9b7297a0758
fix bug in example (should close file at all times)
Guido van Rossum <guido@python.org>
parents:
2647
diff
changeset
|
169 # Shouldn't get here at all. |
|
c9b7297a0758
fix bug in example (should close file at all times)
Guido van Rossum <guido@python.org>
parents:
2647
diff
changeset
|
170 raise ImportError, '%s: unknown module type (%d)' % (name, type) |
|
c9b7297a0758
fix bug in example (should close file at all times)
Guido van Rossum <guido@python.org>
parents:
2647
diff
changeset
|
171 finally: |
|
c9b7297a0758
fix bug in example (should close file at all times)
Guido van Rossum <guido@python.org>
parents:
2647
diff
changeset
|
172 # Since we may exit via an exception, close fp explicitly. |
|
c9b7297a0758
fix bug in example (should close file at all times)
Guido van Rossum <guido@python.org>
parents:
2647
diff
changeset
|
173 fp.close() |
| 2110 | 174 \end{verbatim} |