1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
|
\section{Built-in module \sectcode{imp}}
\bimodindex{imp}
\index{import}
This module provides an interface to the mechanisms used to implement
the \code{import} statement. It defines the following constants and
functions:
\renewcommand{\indexsubitem}{(in module struct)}
\begin{funcdesc}{get_magic}{}
Return the magic string used to recognize value byte-compiled code
files (``\code{.pyc} files'').
\end{funcdesc}
\begin{funcdesc}{get_suffixes}{}
Return a list of triples, each describing a particular type of file.
Each triple has the form \code{(\var{suffix}, \var{mode},
\var{type})}, where \var{suffix} is a string to be appended to the
module name to form the filename to search for, \var{mode} is the mode
string to pass to the built-in \code{open} function to open the file
(this can be \code{'r'} for text files or \code{'rb'} for binary
files), and \var{type} is the file type, which has one of the values
\code{PY_SOURCE}, \code{PY_COMPILED} or \code{C_EXTENSION}, defined
below.
\end{funcdesc}
\begin{funcdesc}{find_module}{name\, \optional{path}}
Try to find the module \var{name} on the search path \var{path}. The
default \var{path} is \code{sys.path}. The return value is a triple
\code{(\var{file}, \var{pathname}, \var{description})} where
\var{file} is an open file object positioned at the beginning
corresponding to the file found, \var{pathname} is the pathname of the
file found, and \var{description} is a triple as contained in the list
returned by \code{get_suffixes} describing the kind of file found.
\end{funcdesc}
\begin{funcdesc}{init_builtin}{name}
Initialize the built-in module called \var{name} and return its module
object. If the module was already initialized, it will be initialized
{\em again}. A few modules cannot be initialized twice --- attempting
to initialize these again will raise an \code{ImportError} exception.
If there is no
built-in module called \var{name}, \code{None} is returned.
\end{funcdesc}
\begin{funcdesc}{init_frozen}{name}
Initialize the frozen module called \var{name} and return its module
object. If the module was already initialized, it will be initialized
{\em again}. If there is no frozen module called \var{name},
\code{None} is returned. (Frozen modules are modules written in
Python whose compiled byte-code object is incorporated into a
custom-built Python interpreter by Python's \code{freeze} utility.
See \code{Demo/freeze} for now.)
\end{funcdesc}
\begin{funcdesc}{is_builtin}{name}
Return \code{1} if there is a built-in module called \var{name} which can be
initialized again. Return \code{-1} if there is a built-in module
called \var{name} which cannot be initialized again (see
\code{init_builtin}). Return \code{0} if there is no built-in module
called \var{name}.
\end{funcdesc}
\begin{funcdesc}{is_frozen}{name}
Return \code{1} if there is a frozen module (see \code{init_frozen})
called \var{name}, \code{0} if there is no such module.
\end{funcdesc}
\begin{funcdesc}{load_compiled}{name\, pathname\, \optional{file}}
Load and initialize a module implemented as a byte-compiled code file
and return its module object. If the module was already initialized,
it will be initialized {\em again}. The \var{name} argument is used
to create or access a module object. The \var{pathname} argument
points to the byte-compiled code file. The optional \var{file}
argument is the byte-compiled code file, open for reading in binary
mode, from the beginning --- if not given, the function opens
\var{pathname}. It must currently be a real file object, not a
user-defined class emulating a file.
\end{funcdesc}
\begin{funcdesc}{load_dynamic}{name\, pathname\, \optional{file}}
Load and initialize a module implemented as a dynamically loadable
shared library and return its module object. If the module was
already initialized, it will be initialized {\em again}. Some modules
don't like that and may raise an exception. The \var{pathname}
argument must point to the shared library. The \var{name} argument is
used to construct the name of the initialization function: an external
C function called \code{init\var{name}()} in the shared library is
called. The optional \var{file} argment is ignored. (Note: using
shared libraries is highly system dependent, and not all systems
support it.)
\end{funcdesc}
\begin{funcdesc}{load_source}{name\, pathname\, \optional{file}}
Load and initialize a module implemented as a Python source file and
return its module object. If the module was already initialized, it
will be initialized {\em again}. The \var{name} argument is used to
create or access a module object. The \var{pathname} argument points
to the source file. The optional \var{file} argument is the source
file, open for reading as text, from the beginning --- if not given,
the function opens \var{pathname}. It must currently be a real file
object, not a user-defined class emulating a file. Note that if a
properly matching byte-compiled file (with suffix \code{.pyc}) exists,
it will be used instead of parsing the given source file.
\end{funcdesc}
\begin{funcdesc}{new_module}{name}
Return a new empty module object called \var{name}. This object is
{\em not} inserted in \code{sys.modules}.
\end{funcdesc}
The following constants with integer values, defined in the module,
are used to indicate the search result of \code{imp.find_module}.
\begin{datadesc}{SEARCH_ERROR}
The module was not found.
\end{datadesc}
\begin{datadesc}{PY_SOURCE}
The module was found as a source file.
\end{datadesc}
\begin{datadesc}{PY_COMPILED}
The module was found as a compiled code object file.
\end{datadesc}
\begin{datadesc}{C_EXTENSION}
The module was found as dynamically loadable shared library.
\end{datadesc}
\subsection{Examples}
The following function emulates the default import statement:
\begin{verbatim}
import imp
from sys import modules
def __import__(name, globals=None, locals=None, fromlist=None):
# Fast path: let's see if it's already in sys.modules.
# Two speed optimizations are worth mentioning:
# - We use 'modules' instead of 'sys.modules'; this saves a
# dictionary look-up per call.
# - It's also faster to use a try-except statement than
# to use modules.has_key(name) to check if it's there.
try:
return modules[name]
except KeyError:
pass
# See if it's a built-in module
m = imp.init_builtin(name)
if m:
return m
# See if it's a frozen module
m = imp.init_frozen(name)
if m:
return m
# Search the default path (i.e. sys.path).
# If this raises an exception, the module is not found --
# let the caller handle the exception.
fp, pathname, (suffix, mode, type) = imp.find_module(name)
# See what we got.
# Note that fp will be closed automatically when we return.
if type == imp.C_EXTENSION:
return imp.load_dynamic(name, pathname)
if type == imp.PY_SOURCE:
return imp.load_source(name, pathname, fp)
if type == imp.PY_COMPILED:
return imp.load_source(name, pathname, fp)
# Shouldn't get here at all.
raise ImportError, '%s: unknown module type (%d)' % (name, type)
\end{verbatim}
|
