Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 1 | \section{Built-in Module \sectcode{imp}} |
Guido van Rossum | 946805d | 1995-01-10 10:51:08 +0000 | [diff] [blame] | 2 | \bimodindex{imp} |
| 3 | \index{import} |
| 4 | |
Guido van Rossum | 6c4f003 | 1995-03-07 10:14:09 +0000 | [diff] [blame] | 5 | This module provides an interface to the mechanisms used to implement |
Guido van Rossum | 946805d | 1995-01-10 10:51:08 +0000 | [diff] [blame] | 6 | the \code{import} statement. It defines the following constants and |
| 7 | functions: |
| 8 | |
Guido van Rossum | 0bbbea1 | 1995-08-10 14:21:11 +0000 | [diff] [blame] | 9 | \renewcommand{\indexsubitem}{(in module imp)} |
Guido van Rossum | 946805d | 1995-01-10 10:51:08 +0000 | [diff] [blame] | 10 | |
| 11 | \begin{funcdesc}{get_magic}{} |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 12 | Return the magic string value used to recognize byte-compiled code |
Guido van Rossum | 946805d | 1995-01-10 10:51:08 +0000 | [diff] [blame] | 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 |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 25 | below. (System-dependent values may also be returned.) |
Guido van Rossum | 946805d | 1995-01-10 10:51:08 +0000 | [diff] [blame] | 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 |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 32 | \var{file} is an open file object positioned at the beginning, |
| 33 | \var{pathname} is the pathname of the |
Guido van Rossum | 946805d | 1995-01-10 10:51:08 +0000 | [diff] [blame] | 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 |
Guido van Rossum | 8675115 | 1995-02-28 17:14:32 +0000 | [diff] [blame] | 41 | {\em again}. A few modules cannot be initialized twice --- attempting |
Guido van Rossum | 6bb1adc | 1995-03-13 10:03:32 +0000 | [diff] [blame] | 42 | to initialize these again will raise an \code{ImportError} exception. |
| 43 | If there is no |
Guido van Rossum | 946805d | 1995-01-10 10:51:08 +0000 | [diff] [blame] | 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. |
Guido van Rossum | ecde781 | 1995-03-28 13:35:14 +0000 | [diff] [blame] | 54 | See \code{Tools/freeze} for now.) |
Guido van Rossum | 946805d | 1995-01-10 10:51:08 +0000 | [diff] [blame] | 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 | |
| 70 | \begin{funcdesc}{load_compiled}{name\, pathname\, \optional{file}} |
| 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 |
| 75 | points to the byte-compiled code file. The optional \var{file} |
| 76 | argument is the byte-compiled code file, open for reading in binary |
Guido van Rossum | 8675115 | 1995-02-28 17:14:32 +0000 | [diff] [blame] | 77 | mode, from the beginning --- if not given, the function opens |
Guido van Rossum | 946805d | 1995-01-10 10:51:08 +0000 | [diff] [blame] | 78 | \var{pathname}. It must currently be a real file object, not a |
| 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 | |
| 95 | \begin{funcdesc}{load_source}{name\, pathname\, \optional{file}} |
| 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 |
| 100 | to the source file. The optional \var{file} argument is the source |
Guido van Rossum | 8675115 | 1995-02-28 17:14:32 +0000 | [diff] [blame] | 101 | file, open for reading as text, from the beginning --- if not given, |
Guido van Rossum | 946805d | 1995-01-10 10:51:08 +0000 | [diff] [blame] | 102 | the function opens \var{pathname}. It must currently be a real file |
| 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 |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 137 | import sys |
Guido van Rossum | 946805d | 1995-01-10 10:51:08 +0000 | [diff] [blame] | 138 | |
Guido van Rossum | 4f4c9b4 | 1995-02-15 15:52:13 +0000 | [diff] [blame] | 139 | def __import__(name, globals=None, locals=None, fromlist=None): |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 140 | # Fast path: see if the module has already been imported. |
| 141 | if sys.modules.has_key(name): |
| 142 | return sys.modules[name] |
Guido van Rossum | 946805d | 1995-01-10 10:51:08 +0000 | [diff] [blame] | 143 | |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 144 | # If any of the following calls raises an exception, |
Guido van Rossum | 96628a9 | 1995-04-10 11:34:00 +0000 | [diff] [blame] | 145 | # there's a problem we can't handle -- let the caller handle it. |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 146 | |
| 147 | # See if it's a built-in module. |
Guido van Rossum | 946805d | 1995-01-10 10:51:08 +0000 | [diff] [blame] | 148 | m = imp.init_builtin(name) |
| 149 | if m: |
| 150 | return m |
| 151 | |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 152 | # See if it's a frozen module. |
Guido van Rossum | 946805d | 1995-01-10 10:51:08 +0000 | [diff] [blame] | 153 | m = imp.init_frozen(name) |
| 154 | if m: |
| 155 | return m |
| 156 | |
| 157 | # Search the default path (i.e. sys.path). |
Guido van Rossum | 946805d | 1995-01-10 10:51:08 +0000 | [diff] [blame] | 158 | fp, pathname, (suffix, mode, type) = imp.find_module(name) |
| 159 | |
| 160 | # See what we got. |
Guido van Rossum | d6ac380 | 1995-07-07 23:01:27 +0000 | [diff] [blame] | 161 | try: |
| 162 | if type == imp.C_EXTENSION: |
| 163 | return imp.load_dynamic(name, pathname) |
| 164 | if type == imp.PY_SOURCE: |
| 165 | return imp.load_source(name, pathname, fp) |
| 166 | if type == imp.PY_COMPILED: |
| 167 | return imp.load_compiled(name, pathname, fp) |
Guido van Rossum | 946805d | 1995-01-10 10:51:08 +0000 | [diff] [blame] | 168 | |
Guido van Rossum | d6ac380 | 1995-07-07 23:01:27 +0000 | [diff] [blame] | 169 | # Shouldn't get here at all. |
| 170 | raise ImportError, '%s: unknown module type (%d)' % (name, type) |
| 171 | finally: |
| 172 | # Since we may exit via an exception, close fp explicitly. |
| 173 | fp.close() |
Guido van Rossum | 946805d | 1995-01-10 10:51:08 +0000 | [diff] [blame] | 174 | \end{verbatim} |