rest25/library/imp.rst => rest262/library/imp.rst
17   .. index:: pair: file; byte-code
18
19   Return the magic string value used to recognize byte-compiled code files
20   (:file:`.pyc` files).  (This value may be different for each Python version.)
21
22
23.. function:: get_suffixes()
24
n25-   Return a list of triples, each describing a particular type of module. Each
n25+   Return a list of 3-element tuples, each describing a particular type of
26-   triple has the form ``(suffix, mode, type)``, where *suffix* is a string to be
26+   module. Each triple has the form ``(suffix, mode, type)``, where *suffix* is
27-   appended to the module name to form the filename to search for, *mode* is the
27+   a string to be appended to the module name to form the filename to search
28-   mode string to pass to the built-in :func:`open` function to open the file (this
28+   for, *mode* is the mode string to pass to the built-in :func:`open` function
29-   can be ``'r'`` for text files or ``'rb'`` for binary files), and *type* is the
29+   to open the file (this can be ``'r'`` for text files or ``'rb'`` for binary
30-   file type, which has one of the values :const:`PY_SOURCE`, :const:`PY_COMPILED`,
30+   files), and *type* is the file type, which has one of the values
31-   or :const:`C_EXTENSION`, described below.
31+   :const:`PY_SOURCE`, :const:`PY_COMPILED`, or :const:`C_EXTENSION`, described
32+   below.
32
33
34.. function:: find_module(name[, path])
35
n36-   Try to find the module *name* on the search path *path*.  If *path* is a list of
n37+   Try to find the module *name* on the search path *path*.  If *path* is a list
37-   directory names, each directory is searched for files with any of the suffixes
38+   of directory names, each directory is searched for files with any of the
38-   returned by :func:`get_suffixes` above.  Invalid names in the list are silently
39+   suffixes returned by :func:`get_suffixes` above.  Invalid names in the list
39-   ignored (but all list items must be strings).  If *path* is omitted or ``None``,
40+   are silently ignored (but all list items must be strings).  If *path* is
40-   the list of directory names given by ``sys.path`` is searched, but first it
41+   omitted or ``None``, the list of directory names given by ``sys.path`` is
41-   searches a few special places: it tries to find a built-in module with the given
42+   searched, but first it searches a few special places: it tries to find a
42-   name (:const:`C_BUILTIN`), then a frozen module (:const:`PY_FROZEN`), and on
43+   built-in module with the given name (:const:`C_BUILTIN`), then a frozen
43-   some systems some other places are looked in as well (on the Mac, it looks for a
44+   module (:const:`PY_FROZEN`), and on some systems some other places are looked
44-   resource (:const:`PY_RESOURCE`); on Windows, it looks in the registry which may
45+   in as well (on Windows, it looks in the registry which may point to a
45-   point to a specific file).
46+   specific file).
46
n47-   If search is successful, the return value is a triple ``(file, pathname,
n48+   If search is successful, the return value is a 3-element tuple ``(file,
49+   pathname, description)``:
50+ 
48-   description)`` where *file* is an open file object positioned at the beginning,
51+   *file* is an open file object positioned at the beginning, *pathname* is the
49-   *pathname* is the pathname of the file found, and *description* is a triple as
52+   pathname of the file found, and *description* is a 3-element tuple as
50   contained in the list returned by :func:`get_suffixes` describing the kind of
n54+   module found.
55+ 
51-   module found. If the module does not live in a file, the returned *file* is
56+   If the module does not live in a file, the returned *file* is ``None``,
52-   ``None``, *filename* is the empty string, and the *description* tuple contains
57+   *pathname* is the empty string, and the *description* tuple contains empty
53-   empty strings for its suffix and mode; the module type is as indicate in
58+   strings for its suffix and mode; the module type is indicated as given in
54-   parentheses above.  If the search is unsuccessful, :exc:`ImportError` is raised.
59+   parentheses above.  If the search is unsuccessful, :exc:`ImportError` is
55-   Other exceptions indicate problems with the arguments or environment.
60+   raised.  Other exceptions indicate problems with the arguments or
61+   environment.
56
n63+   If the module is a package, *file* is ``None``, *pathname* is the package
64+   path and the last item in the *description* tuple is :const:`PKG_DIRECTORY`.
65+ 
57-   This function does not handle hierarchical module names (names containing dots).
66+   This function does not handle hierarchical module names (names containing
58-   In order to find *P*.*M*, that is, submodule *M* of package *P*, use
67+   dots).  In order to find *P*.*M*, that is, submodule *M* of package *P*, use
59   :func:`find_module` and :func:`load_module` to find and load package *P*, and
60   then use :func:`find_module` with the *path* argument set to ``P.__path__``.
61   When *P* itself has a dotted name, apply this recipe recursively.
62
63
n64-.. function:: load_module(name, file, filename, description)
n73+.. function:: load_module(name, file, pathname, description)
65
66   .. index:: builtin: reload
67
68   Load a module that was previously found by :func:`find_module` (or by an
69   otherwise conducted search yielding compatible results).  This function does
70   more than importing the module: if the module was already imported, it is
n71-   equivalent to a :func:`reload`!  The *name* argument indicates the full module
n80+   equivalent to a :func:`reload`!  The *name* argument indicates the full
72-   name (including the package name, if this is a submodule of a package).  The
81+   module name (including the package name, if this is a submodule of a
73-   *file* argument is an open file, and *filename* is the corresponding file name;
82+   package).  The *file* argument is an open file, and *pathname* is the
74-   these can be ``None`` and ``''``, respectively, when the module is not being
83+   corresponding file name; these can be ``None`` and ``''``, respectively, when
75-   loaded from a file.  The *description* argument is a tuple, as would be returned
84+   the module is a package or not being loaded from a file.  The *description*
76-   by :func:`get_suffixes`, describing what kind of module must be loaded.
85+   argument is a tuple, as would be returned by :func:`get_suffixes`, describing
86+   what kind of module must be loaded.
77
n78-   If the load is successful, the return value is the module object; otherwise, an
n88+   If the load is successful, the return value is the module object; otherwise,
79-   exception (usually :exc:`ImportError`) is raised.
89+   an exception (usually :exc:`ImportError`) is raised.
80
n81-   **Important:** the caller is responsible for closing the *file* argument, if it
n91+   **Important:** the caller is responsible for closing the *file* argument, if
82-   was not ``None``, even when an exception is raised.  This is best done using a
92+   it was not ``None``, even when an exception is raised.  This is best done
83-   :keyword:`try` ... :keyword:`finally` statement.
93+   using a :keyword:`try` ... :keyword:`finally` statement.
84
85
86.. function:: new_module(name)
87
88   Return a new empty module object called *name*.  This object is *not* inserted
89   in ``sys.modules``.
90
91
99   import until the original import completes, which in turn prevents other threads
100   from seeing incomplete module objects constructed by the original thread while
101   in the process of completing its import (and the imports, if any, triggered by
102   that).
103
104
105.. function:: acquire_lock()
106
n107-   Acquires the interpreter's import lock for the current thread.  This lock should
n117+   Acquire the interpreter's import lock for the current thread.  This lock should
108   be used by import hooks to ensure thread-safety when importing modules. On
109   platforms without threads, this function does nothing.
110
n121+   Once a thread has acquired the import lock, the same thread may acquire it
122+   again without blocking; the thread must release it once for each time it has
123+   acquired it.
124+ 
125+   On platforms without threads, this function does nothing.
126+ 
111   .. versionadded:: 2.3
112
113
114.. function:: release_lock()
115
116   Release the interpreter's import lock. On platforms without threads, this
117   function does nothing.
118
130.. data:: PY_COMPILED
131
132   The module was found as a compiled code object file.
133
134
135.. data:: C_EXTENSION
136
137   The module was found as dynamically loadable shared library.
n138- 
139- 
140-.. data:: PY_RESOURCE
141- 
142-   The module was found as a Mac OS 9 resource.  This value can only be returned on
143-   a Mac OS 9 or earlier Macintosh.
144
145
146.. data:: PKG_DIRECTORY
147
148   The module was found as a package directory.
149
150
151.. data:: C_BUILTIN
164
165.. data:: SEARCH_ERROR
166
167   Unused.
168
169
170.. function:: init_builtin(name)
171
n172-   Initialize the built-in module called *name* and return its module object.  If
n182+   Initialize the built-in module called *name* and return its module object along
173-   the module was already initialized, it will be initialized *again*.  A few
183+   with storing it in ``sys.modules``.  If the module was already initialized, it
174-   modules cannot be initialized twice --- attempting to initialize these again
184+   will be initialized *again*.  Re-initialization involves the copying of the
175-   will raise an :exc:`ImportError` exception.  If there is no built-in module
185+   built-in module's ``__dict__`` from the cached module over the module's entry in
176-   called *name*, ``None`` is returned.
186+   ``sys.modules``.  If there is no built-in module called *name*, ``None`` is
187+   returned.
177
178
179.. function:: init_frozen(name)
180
n181-   Initialize the frozen module called *name* and return its module object.  If the
n192+   Initialize the frozen module called *name* and return its module object.  If
182-   module was already initialized, it will be initialized *again*.  If there is no
193+   the module was already initialized, it will be initialized *again*.  If there
183-   frozen module called *name*, ``None`` is returned.  (Frozen modules are modules
194+   is no frozen module called *name*, ``None`` is returned.  (Frozen modules are
184-   written in Python whose compiled byte-code object is incorporated into a custom-
195+   modules written in Python whose compiled byte-code object is incorporated
185-   built Python interpreter by Python's :program:`freeze` utility. See
196+   into a custom-built Python interpreter by Python's :program:`freeze`
186-   :file:`Tools/freeze/` for now.)
197+   utility. See :file:`Tools/freeze/` for now.)
187
188
189.. function:: is_builtin(name)
190
191   Return ``1`` if there is a built-in module called *name* which can be
192   initialized again.  Return ``-1`` if there is a built-in module called *name*
193   which cannot be initialized again (see :func:`init_builtin`).  Return ``0`` if
194   there is no built-in module called *name*.
212   from the beginning. It must currently be a real file object, not a user-defined
213   class emulating a file.
214
215
216.. function:: load_dynamic(name, pathname[, file])
217
218   Load and initialize a module implemented as a dynamically loadable shared
219   library and return its module object.  If the module was already initialized, it
n220-   will be initialized *again*.  Some modules don't like that and may raise an
n231+   will be initialized *again*. Re-initialization involves copying the ``__dict__``
221-   exception.  The *pathname* argument must point to the shared library.  The
232+   attribute of the cached instance of the module over the value used in the module
222-   *name* argument is used to construct the name of the initialization function: an
233+   cached in ``sys.modules``.  The *pathname* argument must point to the shared
223-   external C function called ``initname()`` in the shared library is called.  The
234+   library.  The *name* argument is used to construct the name of the
224-   optional *file* argument is ignored.  (Note: using shared libraries is highly
235+   initialization function: an external C function called ``initname()`` in the
225-   system dependent, and not all systems support it.)
236+   shared library is called.  The optional *file* argument is ignored.  (Note:
237+   using shared libraries is highly system dependent, and not all systems support
238+   it.)
226
227
228.. function:: load_source(name, pathname[, file])
229
230   Load and initialize a module implemented as a Python source file and return its
231   module object.  If the module was already initialized, it will be initialized
232   *again*.  The *name* argument is used to create or access a module object.  The
233   *pathname* argument points to the source file.  The *file* argument is the
234   source file, open for reading as text, from the beginning. It must currently be
235   a real file object, not a user-defined class emulating a file.  Note that if a
236   properly matching byte-compiled file (with suffix :file:`.pyc` or :file:`.pyo`)
237   exists, it will be used instead of parsing the given source file.
238
239
240.. class:: NullImporter(path_string)
241
t242-   The :class:`NullImporter` type is a :pep:`302` import hook that handles non-
t255+   The :class:`NullImporter` type is a :pep:`302` import hook that handles
243-   directory path strings by failing to find any modules.  Calling this type with
256+   non-directory path strings by failing to find any modules.  Calling this type
244-   an existing directory or empty string raises :exc:`ImportError`.  Otherwise, a
257+   with an existing directory or empty string raises :exc:`ImportError`.
245-   :class:`NullImporter` instance is returned.
258+   Otherwise, a :class:`NullImporter` instance is returned.
246
247   Python adds instances of this type to ``sys.path_importer_cache`` for any path
248   entries that are not directories and are not handled by any other path hooks on
249   ``sys.path_hooks``.  Instances have only one method:
250
251
252   .. method:: NullImporter.find_module(fullname [, path])
253
Legends
Colors
 Added 
Changed
Deleted
Links
(f)irst change
(n)ext change
(t)op